@guiexpert/table 1.1.84 → 1.1.86

package/lib/table/data/tablemodel/areamodel/area-model-array-of-arrays.d.ts

@@ -20,5 +20,12 @@ export declare class AreaModelArrayOfArrays<T> extends AbstractAreaModel<T[][]>
     setValue(rowIndex: number, columnIndex: number, value: any): boolean;
     getRowByIndex(rowIndex: number): any;
     getRowHeight(_rowIndex: number): number;
+    /**
+     * All rows share `defaultRowHeight` – unless a subclass overrides `getRowHeight()`, then row heights may
+     * vary and `undefined` is returned.
+     *
+     * @returns {number | undefined} The constant row height or `undefined`.
+     */
+    getConstantRowHeight(): number | undefined;
     changeColumnOrder(sourceColumnIndex: number, targetColumnIndex: number): void;
 }

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

@@ -381,6 +381,13 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
      * console.log(`The first row has a height of ${rowHeight}px`);
      */
     getRowHeight(_rowIndex: number): number;
+    /**
+     * All rows share `defaultRowHeight` – unless a subclass overrides `getRowHeight()`, then row heights may
+     * vary and `undefined` is returned.
+     *
+     * @returns {number | undefined} The constant row height or `undefined`.
+     */
+    getConstantRowHeight(): number | undefined;
     /**
      * Returns the row object at the specified index from the filtered rows array.
      * This method overrides the parent class implementation.

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

@@ -32,6 +32,13 @@ export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
     getRowCount(): number;
     getValueAt(rowIndex: number, columnIndex: number): any;
     getRowHeight(_rowIndex: number): number;
+    /**
+     * All rows share `defaultRowHeight` – unless a subclass overrides `getRowHeight()`, then row heights may
+     * vary and `undefined` is returned.
+     *
+     * @returns {number | undefined} The constant row height or `undefined`.
+     */
+    getConstantRowHeight(): number | undefined;
     getCustomClassesAt(rowIndex: number, _columnIndex: number): string[];
     getRowByIndex(idx: number): TreeRowIf<S> | undefined;
     getValueByT(t: S, property: string): any;

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

@@ -500,10 +500,11 @@ export declare class AreaModel implements AreaModelIf {
     /**
      * Returns the Y-coordinate (in pixels) of the top of the row at the specified index.
      * This method is used for scrolling and positioning rows in the viewport.
-     * The base implementation returns 0 and should be overridden by
-     * subclasses that support scrolling.
+     * The base implementation computes it from `getConstantRowHeight()` (O(1)) or by summing up
+     * `getRowHeight()` of all rows above (O(n)) – override it for large models with variable row heights.
+     * (Before 1.1.85 the base implementation returned 0.)
      *
-     * @param {number} _rowIndex - The index of the row
+     * @param {number} rowIndex - The index of the row
      * @returns {number} The Y-coordinate of the top of the row, in pixels
      *
      * @example
@@ -526,7 +527,15 @@ export declare class AreaModel implements AreaModelIf {
      *   // return yPos;
      * }
      */
-    getYPosByRowIndex(_rowIndex: number): number;
+    getYPosByRowIndex(rowIndex: number): number;
+    /**
+     * Returns the row height if all rows have the same height, otherwise `undefined` (default).
+     * Override it together with `getRowHeight()` if your rows have a constant height – this makes rendering
+     * of very large tables independent of the scroll position.
+     *
+     * @returns {number | undefined} `undefined` in the base implementation.
+     */
+    getConstantRowHeight(): number | undefined;
     /**
      * Initializes the area model.
      * This method is called internally by the TableModel during initialization.

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

@@ -565,6 +565,22 @@ export interface AreaModelIf {
      * }
      */
     getRowHeight(rowIndex: number): number;
+    /**
+     * Returns the row height if **all** rows of this area have the same height, otherwise `undefined`.
+     *
+     * The renderer uses this value to find the first visible row directly instead of summing up the heights
+     * 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.
+     *
+     * @returns {number | undefined} The constant row height in pixels, or `undefined` if row heights may vary.
+     *
+     * @example
+     * // Custom area model with 34px rows:
+     * getRowHeight(_rowIndex: number): number { return 34; }
+     * getConstantRowHeight(): number | undefined { return 34; }
+     */
+    getConstantRowHeight?(): number | undefined;
     /**
      * Returns the row object at the specified index.
      * This method provides access to the underlying data structure.

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

@@ -13,6 +13,13 @@ export declare class EleScope {
     readonly tableModel: TableModelIf;
     protected readonly dom: ConvenienceDomService;
     readonly tableOptions: TableOptionsIf;
+    /**
+     * Maximum height (px) of the scrollable content wrapper. Taller tables are scrolled proportionally
+     * (rendering is based on the scroll factor anyway): browsers clamp element heights (Chrome ~33.5 million px)
+     * and GPU rasterization loses precision long before (1px borders disappear and text jitters beyond
+     * ~16.7 million px). 8 million px keep sub-pixel precision.
+     */
+    static maxScrollHeightInPx: number;
     scrollViewport: HTMLDivElement;
     protected contentWrapperDiv: HTMLDivElement;
     protected contentDiv: HTMLDivElement;

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

@@ -47,6 +47,17 @@ export declare class RenderScope extends EleScope {
     protected colAndRowspanModels: AreaObjectMapType<ColAndRowspanModel>;
     protected draggingTargetColumnIndex: number;
     protected mouseEvent?: GeMouseEvent;
+    /** Content pixels scrolled out at the top, i.e. the offset that is actually rendered (see adjustBody). */
+    protected contentScrollTop: number;
+    /** Exact content position requested by scrollToPixel() for a capped scroll height (see TableScope). */
+    protected pendingContentScroll?: {
+        scrollTop: number;
+        contentTop: number;
+    };
+    /** Area heights read once at the start of adjustAfterScrolling() (before the DOM is modified). */
+    protected areaHeightsOfRenderPass?: {
+        [key in AreaIdent]?: number;
+    };
     private debounceTimeout?;
     private editorRenderer?;
     private editorRendererColumn?;
@@ -160,6 +171,31 @@ export declare class RenderScope extends EleScope {
      * @protected
      * @return {void}
      */
+    /**
+     * Rounds a pixel offset to whole device pixels. The scroll offsets are derived from a scroll factor and are
+     * fractional; rows and cells placed at fractional positions render blurry text and 1px borders.
+     *
+     * @param {number} px - offset in CSS pixels
+     * @returns {number} offset snapped to the device pixel grid
+     * @protected
+     */
+    protected snapToDevicePixel(px: number): number;
+    /**
+     * True if the table content is taller than {@link EleScope.maxScrollHeightInPx}; then the scroll bar is
+     * scaled and scrollTop is no longer a content pixel position.
+     */
+    isScrollHeightCapped(): boolean;
+    /** Scrollable range of the content in content pixels (content height minus visible body height). */
+    protected getContentScrollRangeY(): number;
+    /** Scrollable range of the scroll viewport in scroll bar pixels. */
+    protected getScrollerRangeY(): number;
+    /**
+     * Mouse wheel on a capped scroll height: scale the wheel delta, so one wheel step still moves the content
+     * by the usual amount of pixels (otherwise it would jump many rows). No-op for normal tables.
+     *
+     * @param {WheelEvent} evt - the wheel event of the scroll viewport
+     */
+    onWheel(evt: WheelEvent): void;
     protected adjustBody(): void;
     /**
      * Returns a number value extracted from the specified attribute of the source element.
@@ -299,6 +335,11 @@ export declare class RenderScope extends EleScope {
      *
      * @return {undefined}
      */
+    /**
+     * Cancels a pending debounced rendering and calls all renderer cleanup functions
+     * (e.g. unmounts framework components rendered into cells). Used by {@link TableScope.destroy}.
+     */
+    protected disposeRendering(): void;
     protected debounce(fn: () => void, delay?: number): void;
     /**
      * Adjusts the dragging column during a mouse move event.

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

@@ -8,6 +8,12 @@ import { TableScope } from './table-scope';
 export declare class ResizeHandler {
     protected tableScope: TableScope;
     protected debounceDelay: number;
+    private readonly resizeObserver;
+    private disconnected;
     constructor(tableScope: TableScope, debounceDelay?: number);
+    /**
+     * Stops observing the host element. Called by {@link TableScope.destroy}.
+     */
+    disconnect(): void;
     private handleResize;
 }

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

@@ -718,6 +718,20 @@ export declare class TableApi {
      * @returns {void}
      */
     repaint(): void;
+    /**
+     * Releases the table: removes all DOM listeners (incl. the window resize listener), stops the
+     * resize observer, calls the cleanup functions of all cell renderers and clears the host element.
+     * The framework wrappers call it automatically when they are unmounted or receive a new table model.
+     *
+     * @example
+     * // Plain TS: replace the table with a new model
+     * tableApi.destroy();
+     * const scope = new TableScope(hostDiv, newModel, new SimpleDomService(), new TableOptions(), new EventAdapter());
+     * scope.firstInit();
+     *
+     * @returns {void}
+     */
+    destroy(): void;
     /**
      * Performs a complete repaint of the table by triggering a hard repaint on the underlying table scope.
      *

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

@@ -57,6 +57,12 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     readonly copyService: CopyServiceIf;
     readonly excelService: ExcelServiceIf;
     licenseManager: LicenseManager;
+    /**
+     * Signal for all DOM listeners of this table (host element, scroll viewport, window).
+     * {@link destroy} aborts it, which removes every listener at once.
+     */
+    readonly listenerAbortController: AbortController;
+    private destroyed;
     mouseHandler: MouseHandler;
     inputHandler: InputHandler;
     resizeHandler: ResizeHandler;
@@ -113,6 +119,27 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @returns {TableScope} This instance of the table scope.
      */
     firstInit(): TableScope;
+    /**
+     * Releases the table: removes all DOM listeners (host element, scroll viewport, window resize),
+     * stops the resize observer, unregisters from the selection and focus model, calls the cleanup
+     * functions of all cell renderers and clears the host element.
+     *
+     * Call it before you create a new `TableScope` for the same host element (e.g. when a framework
+     * wrapper receives a new table model) or when the table is removed from the page.
+     * Calling it twice is harmless.
+     *
+     * @example
+     * const scope = new TableScope(hostDiv, tableModel, new SimpleDomService(), new TableOptions(), new EventAdapter());
+     * scope.firstInit();
+     * // later, e.g. when a new model arrives:
+     * scope.destroy();
+     * new TableScope(hostDiv, newTableModel, new SimpleDomService(), new TableOptions(), new EventAdapter()).firstInit();
+     */
+    destroy(): void;
+    /**
+     * Returns `true` once {@link destroy} has been called.
+     */
+    isDestroyed(): boolean;
     /**
      * Creates a GeMouseEvent object based on a MouseEvent.
      *

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.84",
+  "version": "1.1.86",
+  "license": "MIT",
+  "author": "Dr. Marc Kronberg <info@gui.expert> (https://gui.expert)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guiexperttable/mono.git",
+    "directory": "packages/table"
+  },
+  "homepage": "https://gui.expert",
   "private": false,
   "type": "module",
   "main": "./index.js",
@@ -17,7 +25,9 @@
     ".": {
       "import": "./index.js",
       "require": "./index.cjs"
-    }
+    },
+    "./css/*": "./css/*",
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "tslib": "^2.3.0"
@@ -35,7 +45,8 @@
     "typedoc": "0.25.3",
     "typedoc-plugin-rename-defaults": "^0.7.0",
     "typedoc-plugin-markdown": "3.17.1",
-    "typescript": "5.2.2"
+    "typescript": "5.2.2",
+    "@babel/core": "~7.28.6"
   },
   "scripts": {
     "i": "pnpm i",