@guiexpert/table 1.1.105 → 1.1.107

package/lib/common/platform.d.ts

@@ -0,0 +1,10 @@
+/**
+ * macOS or not – the one place where the table asks for the platform (⌘ shortcuts, ⌥+letter types text,
+ * `aria-keyshortcuts`). Reads `navigator.platform` ("MacIntel", also iPadOS Safari with a keyboard); without a
+ * `navigator` (SSR, Node) `false`. Tests switch the platform here with `vi.spyOn(navigator, "platform", "get")`.
+ *
+ * `navigator.userAgentData.platform` is not used on purpose: only Chromium has it, and the result would be the same.
+ *
+ * @internal
+ */
+export declare function isMacPlatform(): boolean;

package/lib/table/data/common/scroll-position.if.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A scroll position – the argument of {@link TableApi.repaintHard} (since 1.1.107): the rows are counted again and the
+ * table shows this position in the same render pass. A missing axis keeps its position.
+ *
+ * - `px`: the horizontal scroll position from the start (0 = the first center column at the start; right-to-left
+ *   measured from the right edge, see {@link TableOptionsIf.direction}) – the same as the first argument of
+ *   {@link TableApi.scrollToPixel} (scroll bar pixels, not a column offset: for a column use `scrollToIndex`).
+ * - `py`: a **content** position from the top of the first body row (with the heights of open detail rows above) – the same as the second
+ *   argument of {@link TableApi.scrollToPixel}, also exact with a capped scroll height (more than
+ *   {@link EleScope.maxScrollHeightInPx} px of rows).
+ *
+ * @example
+ * // live tail: rows were appended – count them and show row 500,000 (20 px rows) at the top
+ * tableApi.repaintHard({ py: 500_000 * 20 });
+ *
+ * @example
+ * // only horizontally: back to the first column, the vertical position stays
+ * tableApi.repaintHard({ px: 0 });
+ *
+ * @category Table & API
+ * @since 1.1.107
+ */
+export interface ScrollPositionIf {
+    /** Horizontal scroll position in px from the start (like `scrollToPixel`). Missing: the horizontal position stays. */
+    px?: number;
+    /** Vertical content position in px from the top of the first body row. Missing: the vertical position stays. */
+    py?: number;
+}

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

@@ -118,15 +118,25 @@ export interface TableOptionsIf {
      */
     horizontalBorderVisible: boolean;
     /**
-     * The value of the css `overflowX` determines the behavior of horizontal overflow for the table body (scroll port).
+     * The css `overflow-x` of the scroll viewport (`.ge-table-scroll-viewport`): `"auto"` (default) shows the horizontal
+     * scroll bar only when the columns are wider than the table, `"scroll"` always.
      *
-     * @typedef {'auto' | 'scroll'} OverflowX
+     * To hide the scroll bars completely use CSS – there is no `"hidden"` (wheel, touch, keyboard and the API still
+     * scroll, the table lays out without the bars):
+     * ```css
+     * .my-table .ge-table-scroll-viewport { scrollbar-width: none; }
+     * ```
      */
     overflowX: "auto" | "scroll";
     /**
-     * The value of the css `overflowX` determines the behavior of vertical overflow for the table body (scroll port).
+     * The css `overflow-y` of the scroll viewport (`.ge-table-scroll-viewport`): `"auto"` (default) shows the vertical
+     * scroll bar only when the rows are higher than the body, `"scroll"` always.
      *
-     * @typedef {'auto' | 'scroll'} OverflowX
+     * To hide the scroll bars completely use CSS – there is no `"hidden"` (wheel, touch, keyboard and the API still
+     * scroll, the table lays out without the bars):
+     * ```css
+     * .my-table .ge-table-scroll-viewport { scrollbar-width: none; }
+     * ```
      */
     overflowY: "auto" | "scroll";
     /**

package/lib/table/data/tablemodel/areamodel/abstract-area-model.d.ts

@@ -19,6 +19,10 @@ export declare abstract class AbstractAreaModel<T> implements AreaModelIf, HasDe
     private columnValuesInstance?;
     private calcTextRenderer?;
     protected cellRenderers: (CellRendererIf | undefined)[];
+    /**
+     * @deprecated since 1.1.107 – filled by `init()` for `defaultRowHeight -1`, but no longer read:
+     * {@link getYPosByRowIndex} sums `getRowHeight()` (the cache missed rows added after `init()`).
+     */
     protected yPositions: number[];
     /** Cell formulas of the table (since 1.1.99, set by the table for a flat body). @internal */
     sheetCells?: SheetCellsIf;
@@ -41,6 +45,25 @@ export declare abstract class AbstractAreaModel<T> implements AreaModelIf, HasDe
     setRowChecked(rowIndex: number, checked: boolean): void;
     getMaxColspan(): number;
     getMaxRowspan(): number;
+    /**
+     * The top of a row in px from the first row of this area.
+     *
+     * With a constant row height (`getConstantRowHeight()` of the subclass – the built-in models return their
+     * `defaultRowHeight` as long as `getRowHeight()` is not overridden) it is `rowIndex × height` (O(1)); otherwise the
+     * sum of `getRowHeight()` of all rows above (O(n), always up to date). Before 1.1.107 it was
+     * `defaultRowHeight × rowIndex` also when a subclass overrode `getRowHeight()`, and for `defaultRowHeight -1` a cache
+     * from `init()` that missed rows added later. The table itself positions the body rows with its own row layout.
+     *
+     * @param {number} rowIndex - the index of the row
+     * @returns {number} px from the top of the first row
+     *
+     * @example
+     * // a subclass with taller even rows: the positions follow the overridden getRowHeight()
+     * class Striped extends AreaModelObjectArray<any> {
+     *   override getRowHeight(rowIndex: number): number { return rowIndex % 2 ? 20 : 40; }
+     * }
+     * const y = new Striped("body", rows, 34, columnDefs).getYPosByRowIndex(3); // 40 + 20 + 40 = 100
+     */
     getYPosByRowIndex(rowIndex: number): number;
     init(): void;
     abstract externalFilterChanged<T>(predictFn: FilterFunction<T>): void;

package/lib/table/data/tablemodel/areamodel/area-model-cell-groups.d.ts

@@ -47,7 +47,7 @@ export declare class AreaModelCellGroups implements AreaModelIf {
     getTooltipAt(_rowIndex: number, _columnIndex: number): any;
     getValueAt(rowIndex: number, columnIndex: number): any;
     getTextValueAt(rowIndex: number, columnIndex: number): string;
-    getYPosByRowIndex(_rowIndex: number): number;
+    getYPosByRowIndex(rowIndex: number): number;
     getRowHeight(_rowIndex: number): number;
     isEditable(_rowIndex: number, _columnIndex: number): boolean;
     isFilterable(): boolean;

package/lib/table/data/tablemodel/areamodel/area-model.if.d.ts

@@ -663,6 +663,10 @@ export interface AreaModelIf {
      * Returns the height of the row at the specified index, in pixels.
      * This method allows for variable row heights in the table.
      *
+     * The table draws the rows with these heights, and since 1.1.107 the height of the area (scroll height of the body,
+     * height of header and footer) is their sum as well – {@link getConstantRowHeight} × row count if given.
+     * `defaultRowHeights` of the table model only counts if every row height is 0.
+     *
      * @param {number} rowIndex - The index of the row
      * @returns {number} The height of the row in pixels
      *
@@ -699,6 +703,8 @@ export interface AreaModelIf {
      * of all rows above it – with millions of rows this keeps scrolling at the end of the table as fast as at
      * the beginning. Only return a number if `getRowHeight(i)` returns exactly this value for every row.
      * If the method is missing or returns `undefined`, the renderer falls back to iterating the row heights.
+     * The height of the area (the scroll height of the body) is then this value × row count – O(1) – and wins over
+     * `defaultRowHeights` of the table model (since 1.1.107; before, `defaultRowHeights` came first).
      *
      * @returns {number | undefined} The constant row height in pixels, or `undefined` if row heights may vary.
      *

package/lib/table/data/tablemodel/areamodel/cover-grid-body-model.d.ts

@@ -7,7 +7,22 @@ import { SortItem } from '../../common/sort-item.js';
 import { AreaIdent } from '../area-ident.type.js';
 import { SorterService } from '../../../service/sorter.service.js';
 
-/** @category Area models */
+/**
+ * Body of a cover grid: `filteredItems[row * columns + column]` is the item of a tile (`getValueAt`), `columns` =
+ * `floor(width / coverWidth)`. `items` = all items, `filteredItems` = shown items (filter and `sort()` work on it).
+ * Change `coverWidth`/`coverHeight` or the items and call `tableApi.repaintHard()`.
+ *
+ * @example
+ * ```ts
+ * declare const grid: CoverGridTableModel<string>;
+ * const tiles = grid.bodyModel;
+ * tiles.items = ["new-1.jpg", "new-2.jpg"];
+ * tiles.filteredItems = tiles.items;   // or tableApi.externalFilterChanged() with a filter
+ * tableApi.repaintHard();
+ * ```
+ *
+ * @category Area models
+ */
 export declare class CoverGridBodyModel<T> implements AreaModelIf {
     items: T[];
     cellRenderer: CellRendererIf;

package/lib/table/data/tablemodel/cover-grid-table-model.d.ts

@@ -9,7 +9,20 @@ import { ColumnDefIf } from './column/column-def.if.js';
 import { Padding } from './padding.js';
 import { SelectionModelIf } from '../../selection/selection-model.if.js';
 
-/** @category Table model */
+/**
+ * Table model of a cover grid (created by {@link CoverGridFactory.createCoverGridModel}): items as tiles, the number of
+ * columns follows the width (`floor(width / coverWidth)`), header and footer are hidden. The data and the tile size
+ * live in {@link CoverGridBodyModel} (`tableModel.bodyModel`).
+ *
+ * @example
+ * ```ts
+ * declare const grid: CoverGridTableModel<{ title: string }>;
+ * const columns = grid.getColumnCount();
+ * tableApi.scrollToIndex(0, Math.floor(500 / columns));   // the row of item 500
+ * ```
+ *
+ * @category Table model
+ */
 export declare class CoverGridTableModel<T> implements TableModelIf {
     bodyModel: CoverGridBodyModel<T>;
     paddingTop: number;
@@ -39,6 +52,7 @@ export declare class CoverGridTableModel<T> implements TableModelIf {
     setColumnWidth(_columnIndex: number, width: number): void;
     recalcSize(_clientWidth: number): void;
     recalcPadding(): void;
+    /** No-op: the height follows from the item count, the column count and `coverHeight` – `repaintHard()` is enough. */
     recalcHeightAndPadding(): void;
     getPadding(): Padding;
     getContentHeightInPixel(): number;

package/lib/table/data/tablemodel/table-model.d.ts

@@ -157,10 +157,24 @@ export declare class TableModel implements TableModelIf {
      */
     getModel(rowAreaIdent: AreaIdent): AreaModelIf;
     /**
-     * Calculates the height of the area identified by the given area identifier.
+     * Calculates the height of the area identified by the given area identifier – the height of the rows the table
+     * draws (since 1.1.107 the same source as the rendering):
+     *
+     * 1. `getConstantRowHeight()` of the area model (> 0): row count × that height – O(1), also for millions of rows,
+     * 2. otherwise the sum of `getRowHeight(i)` of all rows (variable heights; O(n), like the row layout of the body),
+     * 3. only if the model has no row heights of its own (every `getRowHeight(i)` is 0): row count ×
+     *    `defaultRowHeights[area]`.
+     *
+     * Before 1.1.107 `defaultRowHeights[area]` came first: an area model with other heights got a wrong scroll height
+     * (a scroll bar without overflow, a wrong thumb). The built-in area models take their row height from
+     * `defaultRowHeights` anyway, so nothing changes for them.
      *
      * @param {AreaIdent} areaIdent - The identifier of the area.
-     * @return {number} - The height of the area.
+     * @return {number} - The height of the area in px.
+     *
+     * @example
+     * // an own body with 20 px rows: 3000 rows are 60,000 px high – also if defaultRowHeights.body is 34
+     * const height = (tableModel as TableModel).getAreaHeight("body");
      */
     getAreaHeight(areaIdent: AreaIdent): number;
     /**

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

@@ -140,11 +140,20 @@ export declare class EleScope {
     /** The element that holds the rows of an area (`DivScope.child`). */
     protected getAreaChild(area: AreaIdent, side: SideIdent): HTMLDivElement;
     /**
-     * Adjusts the containers and rows of the table based on the current state.
+     * Adjusts the containers and rows of the table based on the current state: lays out the areas
+     * ({@link layoutContainers}) and renders the visible rows ({@link adjustAfterScrolling}).
      *
      * @return {void}
      */
     adjustContainersAndRows(): void;
+    /**
+     * Lays out the scroll viewport, the nine areas, the separator borders, the overlay and the detail layer for the
+     * current size of the host and the current padding – without rendering the rows (that is
+     * {@link adjustAfterScrolling}). `repaintHard()` uses it to set a new scroll position before its one render pass.
+     *
+     * @since 1.1.107
+     */
+    protected layoutContainers(): void;
     /**
      * The height the table lays out header, body and footer in: the host height minus a horizontal scroll bar that
      * takes space (see {@link horizontalScrollBarHeight}).

package/lib/table/factory/cover-grid-factory.d.ts

@@ -2,8 +2,73 @@ import { CoverGridTableModel } from '../data/tablemodel/cover-grid-table-model.j
 import { CellRendererIf } from '../renderer/cell-render.if.js';
 import { TableOptionsIf } from '../data/options/table-options.if.js';
 
-/** @category Table model */
+/**
+ * Creates cover grids: a flat array of items shown as tiles (book covers, photos, products) – as many per row as fit
+ * into the width of the table (`floor(width / coverWidth)`), without header and footer. Only the visible rows are
+ * rendered, like in every GuiExpert Table; filter (`externalFilterFunction`), `sort()` and the scroll position work as
+ * usual. Guide: instructions.md 5.10, showcase https://gui.expert/showcase/covergrid/run.
+ *
+ * @example
+ * ```ts
+ * interface Book { title: string; }
+ * declare const books: Book[];
+ *
+ * const renderer: CellRendererIf = {
+ *   render(cellDiv: HTMLDivElement, _r: number, _c: number, _a: AreaIdent, _m: AreaModelIf, book: any) {
+ *     if (book) cellDiv.textContent = (book as Book).title;   // the item of this tile (undefined after the last one)
+ *     return undefined;
+ *   }
+ * };
+ * const gridModel = CoverGridFactory.createCoverGridModel(books, renderer, 160, 240);
+ * const gridOptions = CoverGridFactory.createCoverGrisDefaultOptions(240, () => "books");
+ * const gridApi = new TableScope(host, gridModel, new SimpleDomService(), gridOptions, new EventAdapter())
+ *   .firstInit()
+ *   .getApi();
+ * ```
+ *
+ * @category Table model
+ */
 export declare class CoverGridFactory {
+    /**
+     * Creates the model of a cover grid.
+     *
+     * @param items - the items, one per tile (the renderer gets the item as `cellValue`)
+     * @param cellRenderer - draws one tile into the cell `<div>`
+     * @param coverWidth - width of a tile in px (default 200) – change it later via `bodyModel.coverWidth` + `repaintHard()`
+     * @param coverHeight - height of a tile in px (default 300)
+     * @param width - initial width of the grid; the table sets the width of its host on start and after a resize
+     * @param firstRowPaddingTop - extra height of the first row in px (room above the first tiles, e.g. for a toolbar)
+     * @returns the table model; `tableModel.bodyModel` holds `items`, `filteredItems`, `coverWidth`, `coverHeight`
+     *
+     * @example
+     * ```ts
+     * declare const renderer: CellRendererIf;
+     * const gridModel = CoverGridFactory.createCoverGridModel(["a.jpg", "b.jpg", "c.jpg"], renderer, 120, 180);
+     * // bigger tiles – no new model:
+     * gridModel.bodyModel.coverWidth = 200;
+     * gridModel.bodyModel.coverHeight = 300;
+     * tableApi.repaintHard();
+     * ```
+     */
     static createCoverGridModel<T>(items: T[], cellRenderer: CellRendererIf, coverWidth?: number, coverHeight?: number, width?: number, firstRowPaddingTop?: number): CoverGridTableModel<T>;
+    /**
+     * Options for a cover grid: no borders and separators, no row or column hover, header and footer height 0, and the
+     * scroll position restored under the key of `getStorageKeyFn` (`localStorage`). (The name has a typo – kept for
+     * compatibility.)
+     *
+     * @param defaultRowHeight - the height of a tile (`coverHeight`)
+     * @param getStorageKeyFn - storage key of the scroll position (default `"CoverGrid"`)
+     * @returns new options – add your own fields with a spread
+     *
+     * @example
+     * ```ts
+     * let photoFilter = "";
+     * const gridOptions: TableOptionsIf = {
+     *   ...CoverGridFactory.createCoverGrisDefaultOptions(240, () => "photos"),
+     *   externalFilterFunction: (photo: { name: string }) => photo.name.includes(photoFilter),
+     *   shortcutActionsDisabled: true
+     * };
+     * ```
+     */
     static createCoverGrisDefaultOptions(defaultRowHeight: number, getStorageKeyFn?: () => string): TableOptionsIf;
 }

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

@@ -103,7 +103,12 @@ export interface CreateTableModelPara {
      * @since 1.1.99
      */
     columnLetters: boolean;
-    /** Row heights of header, body and footer in px. Default: `tableOptions.defaultRowHeights`, otherwise 34 / 34 / 34. */
+    /**
+     * Row heights of header, body and footer in px. Default: `tableOptions.defaultRowHeights`, otherwise 34 / 34 / 34.
+     * The area models built by the factory get these heights. An own area model (`bodyAreaModel` …) keeps its own:
+     * since 1.1.107 the table measures every area with the heights of its model (`getConstantRowHeight()`, otherwise
+     * `getRowHeight(i)`) – `defaultRowHeights` only counts for a model whose `getRowHeight()` returns 0.
+     */
     defaultRowHeights: DefaultRowHeightsIf;
     /** The columns: property, header label, width, classes, renderers, sorting, editing. See {@link ColumnDef}. */
     columnDefs: ColumnDefIf[];

package/lib/table/mouse-handler.d.ts

@@ -27,6 +27,10 @@ export declare class MouseHandler {
     private mouseDown;
     private repaintAfterMouseUp;
     private dragging;
+    /** Counts the drags: a frame callback of a drag that is over (a new one started) does nothing. */
+    private dragGeneration;
+    /** The end of the last drag, until its frame ran – a new mousedown handles it at once (see {@link flushDraggingEnd}). */
+    private pendingDraggingEnd?;
     constructor(tableScope: TableScope);
     /**
      * Handles the "contextmenu" event.
@@ -76,7 +80,8 @@ export declare class MouseHandler {
     private onMouseMove;
     private onMouseUp;
     private mouseDraggingOnFrame;
-    private mouseDraggingEndOnFrame;
+    /** Handles the end of the last drag now (in its frame, or earlier when the next mousedown comes first). */
+    private flushDraggingEnd;
     private mouseMoveOnFrame;
     /** A mouse event on a blocking loading overlay ({@link TableOverlay.isEventBlocked}): the table ignores it. */
     private isBlocked;

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

@@ -30,6 +30,7 @@ import { AriaTextsIf } from './aria/aria-texts.if.js';
 import { RowLayout } from './row-layout/row-layout.js';
 import { MasterDetailService } from './master-detail/master-detail-service.js';
 import { TableSheet } from './sheet/table-sheet.js';
+import { ScrollPositionIf } from './data/common/scroll-position.if.js';
 
 /** @category Internals */
 export declare class RenderScope extends EleScope {
@@ -67,6 +68,12 @@ export declare class RenderScope extends EleScope {
         scrollTop: number;
         contentTop: number;
     };
+    /**
+     * The scroll position (`scrollTop`, logical `scrollLeft`) of the last render pass – the `scroll` event of a position
+     * that is already rendered (`repaintHard({ py })`, `scrollToPixel()` render it at once) renders nothing.
+     */
+    protected renderedScrollTop: number;
+    protected renderedScrollLeft: number;
     /** Area heights read once at the start of adjustAfterScrolling() (before the DOM is modified). */
     protected areaHeightsOfRenderPass?: {
         [key in AreaIdent]?: number;
@@ -214,8 +221,10 @@ export declare class RenderScope extends EleScope {
     /** True if open detail rows take space between the body rows. */
     protected hasBodyRowExtras(): boolean;
     /**
-     * The top of a body row in content pixels: {@link AreaModelIf.getYPosByRowIndex} plus the heights of the open detail
-     * rows above it (master/detail).
+     * The top of a body row in content pixels – from the row layout of the table ({@link getBodyRowLayout}: the heights
+     * the rows are drawn with, plus the open detail rows above it). Since 1.1.107 always from the layout (before: without
+     * detail rows from {@link AreaModelIf.getYPosByRowIndex}, which an area model with its own `getRowHeight()` could
+     * get wrong – `scrollToIndex()` landed beside the row). O(1) for constant heights, otherwise after one O(n) build.
      *
      * @param {number} rowIndex - display index
      * @returns {number} px from the top of the first body row
@@ -296,13 +305,39 @@ export declare class RenderScope extends EleScope {
      */
     invalidateAggregates(change?: DerivedValuesChangeIf): void;
     /**
-     * Repaints the UI by resetting the size of the wrapper div,
-     * adjusting the containers and rows, and performing additional adjustments
-     * after scrolling.
+     * Repaints the UI after the row count or the row heights changed: new heights and padding, new size of the scroll
+     * content, new layout of the areas – then **one** render pass (since 1.1.107; before: two).
      *
+     * @param {ScrollPositionIf} [scrollTo] - a content position to show in that render pass (like {@link scrollToPixel},
+     *   exact also with a capped scroll height); a missing axis keeps its position
      * @return {void} This method does not return any value.
      */
-    repaintHard(): void;
+    repaintHard(scrollTo?: ScrollPositionIf): void;
+    /**
+     * Sets the scroll position of the viewport to a content position **without rendering** (shared by
+     * `scrollToPixel()` and `repaintHard({ px, py })`). `py` is a content position: the scroll bar range differs from the
+     * content range – always with a capped scroll height, but also slightly without (the scroll content is 1 px higher
+     * than the rows, the scroll viewport includes the footer and the horizontal scroll bar). `scrollTop = py` would leave
+     * the target row a few pixels off, so the exact content position is remembered (`pendingContentScroll`) and used by
+     * the next render passes as long as the scroll bar is not moved.
+     *
+     * @param {number | undefined} px - from the start of the rows (logical, right-to-left from the right edge);
+     *   `undefined` keeps the horizontal position
+     * @param {number | undefined} py - content px from the top of the first body row; `undefined` keeps the vertical
+     *   position
+     * @returns {boolean} true if the exact content position was set (then render now – a scroll event may not fire);
+     *   false if the browser renders it with its scroll event (nothing to scroll vertically, or only `px`)
+     * @since 1.1.107
+     */
+    protected setContentScrollPosition(px: number | undefined, py: number | undefined): boolean;
+    /**
+     * The `scroll` listener of the scroll viewport: renders the new position – nothing if the position is already
+     * rendered (the event of a `repaintHard({ py })`, `scrollToPixel()` or `ensureColumnIsVisible()` arrives after
+     * their own render pass).
+     *
+     * @since 1.1.107
+     */
+    onViewportScroll(): void;
     /**
      * Recalculates the column widths of the table (% and weight columns depend on the available width) and repaints.
      *
@@ -316,7 +351,7 @@ export declare class RenderScope extends EleScope {
     protected setParentWidth(widthInPixel: number): void;
     /** True if a column has a % or weight width (it depends on the width of the host). */
     protected hasRelativeColumnWidths(): boolean;
-    adjustContainersAndRows(): void;
+    protected layoutContainers(): void;
     /**
      * % and weight columns share the width next to the vertical scroll bar. The bar appears (or disappears) only after
      * the rows are laid out – the first layout, rows added or removed, a filter: then the columns were computed for the
@@ -448,14 +483,14 @@ export declare class RenderScope extends EleScope {
      * scaled and scrollTop is no longer a content pixel position.
      */
     isScrollHeightCapped(): boolean;
+    /** The detail layer (master/detail) covers the visible body. @since 1.1.97 */
+    protected adjustDetailLayerBounds(left: number, top: number, width: number, height: number): void;
     /**
      * The model's content height plus the heights of open detail rows (master/detail).
      *
      * @returns {number} px
      * @since 1.1.97
      */
-    /** The detail layer (master/detail) covers the visible body. @since 1.1.97 */
-    protected adjustDetailLayerBounds(left: number, top: number, width: number, height: number): void;
     protected getBodyContentHeight(): number;
     /** Scrollable range of the content in content pixels (content height minus visible body height). */
     protected getContentScrollRangeY(): number;
@@ -601,7 +636,7 @@ export declare class RenderScope extends EleScope {
      */
     private rowNumberWidth?;
     /** true while the containers are adjusted to a new row number width (no second change in that nested pass). */
-    private adjustingRowNumberWidth;
+    protected adjustingRowNumberWidth: boolean;
     /** Guards {@link adjustRelativeColumnWidthsToScrollBar} against re-entry. */
     private adjustingRelativeWidths;
     /** The width % and weight columns were last computed for (`TableModelIf.setParentWidth`), -1 = unknown. */

package/lib/table/sheet-editing/editors/select-cell-editor.d.ts

@@ -17,6 +17,8 @@ import { ValueLabelIf } from '../../data/common/value-label.if.js';
 export declare class SelectCellEditor implements CellEditorIf {
     protected readonly options: ValueLabelIf[];
     private select?;
+    /** The text of the cell when the editor opened: "nothing chosen" counts as unchanged (since 1.1.106). */
+    private startText;
     private readonly abort;
     constructor(options: ValueLabelIf[]);
     /**
@@ -28,6 +30,12 @@ export declare class SelectCellEditor implements CellEditorIf {
     static create(values: string[]): SelectCellEditor;
     open(container: HTMLDivElement, ctx: CellEditorContextIf): void;
     getValue(): unknown;
+    /**
+     * The chosen value as text; with nothing chosen (the cell's value is not in the list) the start text, so that
+     * Enter without a choice writes nothing (before 1.1.106 it emptied the cell).
+     *
+     * @returns {string} the text
+     */
     getText(): string;
     focus(): void;
     getFocusElement(): HTMLElement | undefined;

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

@@ -27,6 +27,7 @@ import { CellRange } from './data/common/cell-range.js';
 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';
 
 /**
  * The public API of one table – everything you do with a table after it has been created:
@@ -464,19 +465,24 @@ export declare class TableApi {
      */
     destroy(): void;
     /**
-     * Performs a complete repaint of the table by triggering a hard repaint on the underlying table scope.
+     * Performs a complete repaint of the table: use it when the row count or the row heights changed (rows added or
+     * removed, a filter, a new model content, `ColumnDefIf.isVisible` changed yourself …). It
+     * - drops cached derived values (footer totals, calculated columns),
+     * - recalculates the heights and the padding of the table model and the size of the scroll content,
+     * - lays out header, body and footer again and
+     * - renders the visible rows – **once** (since 1.1.107; before: twice).
      *
-     * A hard repaint is more thorough than a regular repaint and performs the following operations:
-     * - Recalculates the height and padding of the table model
-     * - Resets the size of the wrapper div elements
-     * - Adjusts containers and rows positioning
-     * - Makes additional adjustments after scrolling
+     * With `scrollTo` (since 1.1.107) it also sets the scroll position in that same render pass – exactly like
+     * {@link scrollToPixel}, also with a capped scroll height (more than {@link EleScope.maxScrollHeightInPx} px of rows).
+     * A live tail that appends rows and keeps a position needs one render per update instead of three
+     * (`repaintHard()` + `scrollToPixel()`). The `scroll` event of the browser for that position renders nothing.
+     * A missing axis keeps its position.
      *
-     * Use this method when regular repaint isn't sufficient, such as when:
-     * - Table dimensions have significantly changed
-     * - The structure of data has been modified (rows/columns added or removed)
-     * - The table layout needs complete recalculation
-     * - After major DOM changes affecting the table's container
+     * For a repaint with the same row count (values changed) {@link repaint} is enough.
+     *
+     * @param {ScrollPositionIf} [scrollTo] - the position to show: `px` horizontal scroll position from the start, `py`
+     *   content pixels from the top of the first body row (both like {@link scrollToPixel}); without it the position stays
+     * @returns {void} This method doesn't return a value
      *
      * @example
      * // Example 1: Basic usage
@@ -499,9 +505,20 @@ export declare class TableApi {
      * column.isVisible = FalseFn;
      * tableApi.repaintHard();
      *
-     * @returns {void} This method doesn't return a value
+     * @example
+     * // Example 5: live tail – rows were appended to the area model, the first visible row stays at the top
+     * // (pixel-exact: keep your own py from the last update instead – e.g. from onScroll)
+     * const rowHeight = 20;                                   // the row height of the area model
+     * const first = tableApi.getFirstVisibleRowIndex();
+     * rows.push(...newData);                                  // the row count of the model grows
+     * tableApi.repaintHard({ py: first * rowHeight });        // one render pass, exact also for millions of rows
+     *
+     * @example
+     * // Example 6: follow the end ("tail -f") – show the last row after every update
+     * rows.push(...newData);
+     * tableApi.repaintHard({ py: Number.MAX_SAFE_INTEGER }); // clamped to the end of the content
      */
-    repaintHard(): void;
+    repaintHard(scrollTo?: ScrollPositionIf): void;
     /**
      * Recalculates the column widths of the table.
      *

package/package.json

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