@rickcedwhat/playwright-smart-table 6.12.0 → 6.14.0

package/dist/types.d.ts

@@ -37,16 +37,45 @@ export type GetCellLocatorFn = (args: {
     config: FinalTableConfig<any>;
 }) => Locator;
 /**
- * Hook called before each cell value is read in toJSON (and columnOverrides.read).
- * Use this to scroll off-screen columns into view in horizontally virtualized tables,
- * wait for lazy-rendered content, or perform any pre-read setup.
+ * Hook called before each cell value is read in `toJSON` (and `columnOverrides.read`).
+ *
+ * Use this to scroll off-screen columns into view in **horizontally** virtualized tables,
+ * wait for lazy-rendered content (popovers, tooltips, async cell renderers), or perform
+ * any other pre-read setup that doesn't involve Y-axis scrolling.
+ *
+ * ---
+ *
+ * **⚠️ Y-scroll footgun — do NOT call `scrollIntoViewIfNeeded()` on row-virtualized grids.**
+ *
+ * `scrollIntoViewIfNeeded` adjusts *both* scroll axes. On grids that recycle DOM nodes
+ * based on the Y position (MUI DataGrid, AG Grid, react-window, etc.) calling it will
+ * shift the viewport vertically, unmounting the row you are currently reading and
+ * silently returning stale or empty cell values for the remainder of the row.
+ *
+ * Safe uses:
+ * - Column-only (X-axis) virtualization where rows are always in the DOM.
+ * - Calling `scrollIntoViewIfNeeded` on the **header cell** only, when that header is
+ *   guaranteed not to trigger a Y-scroll (e.g. sticky header grids).
+ *
+ * For grids with **both** row and column virtualization, use the `viewport` strategy
+ * instead — it drives explicit `scrollToRow` / `scrollToColumn` calls and is aware of
+ * the virtualization lifecycle.
  *
  * @example
- * // Scroll the column header into view to trigger horizontal virtualization render
+ * // Safe: column-only horizontal virtualization (rows always in DOM)
  * strategies: {
  *   beforeCellRead: async ({ columnName, getHeaderCell }) => {
  *     const header = await getHeaderCell(columnName);
- *     await header.scrollIntoViewIfNeeded();
+ *     await header.scrollIntoViewIfNeeded(); // only scrolls X — rows stay mounted
+ *   }
+ * }
+ *
+ * @example
+ * // Safe: wait for a lazy-rendered popover/tooltip before reading its text
+ * strategies: {
+ *   beforeCellRead: async ({ cell }) => {
+ *     await cell.hover();
+ *     await cell.page().waitForSelector('.cell-tooltip', { state: 'visible' });
  *   }
  * }
  */
@@ -401,6 +430,38 @@ export interface LoadingStrategy {
     isTableLoading?: (context: TableContext) => Promise<boolean>;
     isRowLoading?: (row: SmartRow) => Promise<boolean>;
     isHeaderLoading?: (context: TableContext) => Promise<boolean>;
+    /**
+     * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.
+     * When not set, loading rows are immediately skipped (backward-compatible behavior).
+     */
+    rowLoadingTimeout?: number;
+    /**
+     * What to do when a row is still loading after rowLoadingTimeout ms.
+     * - 'skip': drop the row from results (matches legacy skip behavior)
+     * - 'read-as-is': include the row even though it's still loading (default)
+     * - 'throw': throw an error with row index and timeout info
+     * Defaults to 'read-as-is' when rowLoadingTimeout is set.
+     */
+    onRowLoadingTimeout?: 'skip' | 'read-as-is' | 'throw';
+    /**
+     * Predicate called before reading each cell. Return true if the cell is still loading.
+     * When cellLoadingTimeout is also set, the engine waits up to that many ms for the
+     * cell to resolve before applying onCellLoadingTimeout.
+     */
+    isCellLoading?: (cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<boolean>;
+    /**
+     * How long (ms) to wait for a loading cell to resolve before applying onCellLoadingTimeout.
+     * When not set and isCellLoading returns true, the cell is read as-is immediately.
+     */
+    cellLoadingTimeout?: number;
+    /**
+     * What to do when a cell is still loading after cellLoadingTimeout ms.
+     * - 'skip': use empty string for this cell value
+     * - 'read-as-is': read the cell content even though it's still loading (default)
+     * - 'throw': throw an error with column name, row index and timeout info
+     * Defaults to 'read-as-is' when cellLoadingTimeout is set.
+     */
+    onCellLoadingTimeout?: 'skip' | 'read-as-is' | 'throw';
 }
 /**
  * Organized container for all table interaction strategies.
@@ -516,6 +577,8 @@ export type RowIterationContext<T = any> = {
     rowIndex: number;
     /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
     index: number;
+    /** 0-based page index — which page this row was collected from. */
+    pageIndex: number;
     stop: () => void;
 };
 /** Concurrency modes for row iteration. */
@@ -547,6 +610,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
     row: SmartRow<T>;
     rowIndex: number;
     index: number;
+    pageIndex: number;
 }> {
     /**
      * Represents the current page index of the table's DOM.
@@ -559,7 +623,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     init(options?: {
         timeout?: number;
-    }): Promise<TableResult>;
+    }): Promise<TableResult<T>>;
     /**
      * SYNC: Checks if the table has been initialized.
      * @returns true if init() has been called and completed, false otherwise
@@ -575,13 +639,13 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     getRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
-    }) => SmartRow;
+    }) => SmartRow<T>;
     /**
      * Gets a row by 0-based index on the current page.
      * Throws error if table is not initialized.
      * @param index 0-based row index
      */
-    getRowByIndex: (index: number) => SmartRow;
+    getRowByIndex: (index: number) => SmartRow<T>;
     /**
      * ASYNC: Searches for a single row across pages using pagination.
      * Auto-initializes the table if not already initialized.
@@ -591,7 +655,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
     findRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
-    }) => Promise<SmartRow>;
+    }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for all matching rows across pages using pagination.
      * Auto-initializes the table if not already initialized.

package/dist/useTable.js

@@ -196,6 +196,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         if (pagesJumped > 0) {
             tableState.currentPageIndex += pagesJumped;
             log(`_advancePage: ${primitive} advanced ${pagesJumped} page(s) — now at page ${tableState.currentPageIndex}`);
+            await (0, debugUtils_1.debugDelay)(config, 'pagination');
         }
         else {
             log(`_advancePage: ${primitive} returned false — end of data`);
@@ -261,10 +262,35 @@ const useTable = (rootLocator, configOptions = {}) => {
             return resolve(config.headerSelector, rootLocator).nth(idx);
         },
         countRows: async () => {
-            log("countRows: counting rows in current viewport");
             await _autoInit();
-            const allRows = resolve(config.rowSelector, rootLocator);
-            return allRows.count();
+            const pag = config.strategies.pagination;
+            const hasPagination = config.maxPages > 1 && !!((pag === null || pag === void 0 ? void 0 : pag.goNext) || (pag === null || pag === void 0 ? void 0 : pag.goNextBulk));
+            if (!hasPagination) {
+                log("countRows: counting rows in current viewport (no pagination)");
+                return resolve(config.rowSelector, rootLocator).count();
+            }
+            log(`countRows: paginating up to ${config.maxPages} page(s)`);
+            const tracker = new elementTracker_1.ElementTracker('countRows');
+            let total = 0;
+            let pagesScanned = 1;
+            try {
+                while (true) {
+                    const newIndices = await tracker.getUnseenIndices(resolve(config.rowSelector, rootLocator));
+                    total += newIndices.length;
+                    log(`countRows: page ${pagesScanned} — ${newIndices.length} row(s) (running total: ${total})`);
+                    if (pagesScanned >= config.maxPages)
+                        break;
+                    if (!await _advancePage(false))
+                        break;
+                    pagesScanned++;
+                }
+            }
+            finally {
+                await tracker.cleanup(rootLocator.page());
+            }
+            log(`countRows: ${total} total row(s) across ${pagesScanned} page(s) — resetting`);
+            await result.reset();
+            return total;
         },
         mapColumn: async (columnName, options = {}) => {
             log(`mapColumn: column="${columnName}" options=${safeStringify(options)}`);
@@ -318,8 +344,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw new Error('Initialization Error: You attempted to access a row before the table structure was mapped. Please call "await table.init()" once before using synchronous row access.');
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = filterEngine.applyFilters(allRows, filters, map, options.exact || false, rootLocator.page(), rootLocator);
-            const rowLocator = matchedRows.first();
-            return _makeSmart(rowLocator, map, undefined); // sync path cannot compute real index
+            return _makeSmart(matchedRows, map, undefined); // sync path cannot compute real index
         },
         getRowByIndex: (index) => {
             log(`getRowByIndex: index=${index}`);
@@ -393,6 +418,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 const effectiveMaxPages = config.maxPages;
                 const tracker = new elementTracker_1.ElementTracker('iterator');
                 const useBulk = false; // iterator has no options; default goNext
+                log(`iterator: starting (maxPages=${effectiveMaxPages})`);
                 try {
                     let rowIndex = 0;
                     let pagesScanned = 1;
@@ -402,7 +428,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         const pageRows = yield __await(rowLocators.all());
                         const barrier = new navigationBarrier_1.NavigationBarrier(newIndices.length);
                         for (const idx of newIndices) {
-                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex, pagesScanned - 1, barrier), index: rowIndex, rowIndex });
+                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex, tableState.currentPageIndex, barrier), index: rowIndex, rowIndex, pageIndex: tableState.currentPageIndex });
                             rowIndex++;
                         }
                         if (pagesScanned >= effectiveMaxPages)
@@ -429,6 +455,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
+                getCurrentPageIndex: () => tableState.currentPageIndex,
             }, callback, options);
         },
         map: async (callback, options = {}) => {
@@ -442,6 +469,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
+                getCurrentPageIndex: () => tableState.currentPageIndex,
             }, callback, options);
         },
         filter: async (predicate, options = {}) => {
@@ -455,6 +483,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
+                getCurrentPageIndex: () => tableState.currentPageIndex,
             }, predicate, options);
         },
         generateConfig: async () => {

package/dist/utils/navigationBarrier.d.ts

@@ -7,6 +7,8 @@ export declare class NavigationBarrier {
     private finishedCount;
     private buckets;
     constructor(total: number);
+    /** True when more than one row shares this barrier (scrollToRow would evict peers). */
+    isParallel(): boolean;
     /**
      * Synchronize all active rows at a specific column index.
      * The last row to arrive will trigger the `moveAction`.

package/dist/utils/navigationBarrier.js

@@ -12,6 +12,10 @@ class NavigationBarrier {
         this.buckets = new Map();
         this.total = total;
     }
+    /** True when more than one row shares this barrier (scrollToRow would evict peers). */
+    isParallel() {
+        return this.total > 1;
+    }
     /**
      * Synchronize all active rows at a specific column index.
      * The last row to arrive will trigger the `moveAction`.

package/dist/utils.js

@@ -6,6 +6,7 @@ exports.waitForCondition = void 0;
  * Replaces the dependency on 'expect(...).toPass()' to ensure compatibility
  * with environments where 'expect' is not globally available.
  */
+// fallow-ignore-next-line unused-export
 const waitForCondition = async (predicate, timeout, page) => {
     const startTime = Date.now();
     while (Date.now() - startTime < timeout) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.12.0",
+  "version": "6.14.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "docs:build:all": "vitepress build docs",
     "docs:verify-links": "node scripts/verify-vitepress-links.mjs",
     "embed-version": "node scripts/embed-version.mjs",
+    "generate-og": "node scripts/generate-og.mjs",
     "build": "pnpm run embed-version && pnpm run generate-types && pnpm run generate-config-types && pnpm run generate-docs && pnpm run generate-all-api-docs && pnpm run update-all-api-signatures && tsc",
     "prepublishOnly": "pnpm run build",
     "clean-port": "lsof -ti:3000 | xargs kill -9 || true",
@@ -83,6 +84,8 @@
     "@playwright/test": "^1.40.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@playwright/test": "^1.59.1",
     "@stryker-mutator/core": "^9.6.0",
     "@stryker-mutator/vitest-runner": "^9.6.0",
@@ -90,15 +93,11 @@
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "happy-dom": "^20.8.3",
-    "@commitlint/cli": "^19.7.1",
-    "@commitlint/config-conventional": "^19.7.1",
     "husky": "^9.1.7",
     "typescript": "^6.0.2",
     "vitepress": "^1.6.4",
+    "vitepress-plugin-tabs": "^0.9.0",
     "vitest": "^3.2.4"
   },
-  "dependencies": {
-    "@scarf/scarf": "^1.4.0"
-  },
   "packageManager": "pnpm@10.33.2"
 }

package/dist/presets/glide/columns.d.ts

@@ -1,14 +0,0 @@
-import { StrategyContext } from '../../types';
-/**
- * Primitive navigation functions for Glide Data Grid.
- * These define HOW to move, not WHEN to move.
- * The orchestration logic lives in _navigateToCell.
- */
-export declare const glideGoUp: (context: StrategyContext) => Promise<void>;
-export declare const glideGoDown: (context: StrategyContext) => Promise<void>;
-export declare const glideGoLeft: (context: StrategyContext) => Promise<void>;
-export declare const glideGoRight: (context: StrategyContext) => Promise<void>;
-/** Coarse `scrollLeft` toward `columnIndex`; `goLeft`/`goRight` correct the remainder. */
-export declare const glideSeekColumnIndex: (context: StrategyContext, columnIndex: number) => Promise<void>;
-/** `scrollLeft = 0` so low `aria-colindex` cells exist again (see smartRow for optional `Home`). */
-export declare const glideSnapFirstColumnIntoView: (context: StrategyContext) => Promise<void>;

package/dist/presets/glide/columns.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.glideSnapFirstColumnIntoView = exports.glideSeekColumnIndex = exports.glideGoRight = exports.glideGoLeft = exports.glideGoDown = exports.glideGoUp = void 0;
-/**
- * Primitive navigation functions for Glide Data Grid.
- * These define HOW to move, not WHEN to move.
- * The orchestration logic lives in _navigateToCell.
- */
-const glideGoUp = async (context) => {
-    await context.page.keyboard.press('ArrowUp');
-};
-exports.glideGoUp = glideGoUp;
-const glideGoDown = async (context) => {
-    await context.page.keyboard.press('ArrowDown');
-};
-exports.glideGoDown = glideGoDown;
-// Horizontal: use page `.dvn-scroller` (canvas root is not its ancestor). Virtualized rows expose
-// a small window of `td[aria-colindex]` that shifts with scrollLeft.
-const nudgePageScroller = async (page, delta) => {
-    const scroller = page.locator('.dvn-scroller').first();
-    await scroller.evaluate((el, d) => {
-        el.scrollLeft += d;
-    }, delta);
-};
-const glideGoLeft = async (context) => {
-    await nudgePageScroller(context.page, -400);
-};
-exports.glideGoLeft = glideGoLeft;
-const glideGoRight = async (context) => {
-    await nudgePageScroller(context.page, 400);
-};
-exports.glideGoRight = glideGoRight;
-/** Coarse `scrollLeft` toward `columnIndex`; `goLeft`/`goRight` correct the remainder. */
-const glideSeekColumnIndex = async (context, columnIndex) => {
-    const { page } = context;
-    const scroller = page.locator('.dvn-scroller').first();
-    await scroller.evaluate((el, colIdx) => {
-        const max = Math.max(0, el.scrollWidth - el.clientWidth);
-        const ratio = Math.min(1, Math.max(0, (colIdx + 0.5) / 64));
-        el.scrollLeft = Math.floor(ratio * max);
-    }, columnIndex);
-    await page.waitForTimeout(100);
-};
-exports.glideSeekColumnIndex = glideSeekColumnIndex;
-/** `scrollLeft = 0` so low `aria-colindex` cells exist again (see smartRow for optional `Home`). */
-const glideSnapFirstColumnIntoView = async (context) => {
-    const { page } = context;
-    await page.locator('.dvn-scroller').first().evaluate((el) => {
-        el.scrollLeft = 0;
-    });
-    await page.waitForTimeout(150);
-};
-exports.glideSnapFirstColumnIntoView = glideSnapFirstColumnIntoView;