@rickcedwhat/playwright-smart-table 6.18.0 → 6.20.0

package/dist/useTable.js

@@ -27,6 +27,7 @@ const filterEngine_1 = require("./filterEngine");
 const tableMapper_1 = require("./engine/tableMapper");
 const rowFinder_1 = require("./engine/rowFinder");
 const tableIteration_1 = require("./engine/tableIteration");
+const rowResolution_1 = require("./engine/rowResolution");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
 const elementTracker_1 = require("./utils/elementTracker");
@@ -69,9 +70,11 @@ const useTable = (rootLocator, configOptions = {}) => {
         const vp = config.strategies.viewport;
         let colRangeCache = null;
         let rowRangeCache = null;
+        let rowIndicesCache = null;
         _clearViewportCache = () => {
             colRangeCache = null;
             rowRangeCache = null;
+            rowIndicesCache = null;
         };
         config.strategies.viewport = Object.assign(Object.assign({}, vp), { getVisibleColumnRange: vp.getVisibleColumnRange
                 ? async (ctx) => {
@@ -85,15 +88,23 @@ const useTable = (rootLocator, configOptions = {}) => {
                         rowRangeCache = await vp.getVisibleRowRange(ctx);
                     return rowRangeCache;
                 }
+                : undefined, getVisibleRowIndices: vp.getVisibleRowIndices
+                ? async (ctx) => {
+                    if (!rowIndicesCache)
+                        rowIndicesCache = await vp.getVisibleRowIndices(ctx);
+                    return rowIndicesCache;
+                }
                 : undefined, scrollToColumn: vp.scrollToColumn
                 ? async (ctx, colIndex) => {
                     colRangeCache = null;
                     rowRangeCache = null;
+                    rowIndicesCache = null;
                     await vp.scrollToColumn(ctx, colIndex);
                 }
                 : undefined, scrollToRow: vp.scrollToRow
                 ? async (ctx, rowIndex) => {
                     rowRangeCache = null;
+                    rowIndicesCache = null;
                     await vp.scrollToRow(ctx, rowIndex);
                 }
                 : undefined });
@@ -134,10 +145,16 @@ const useTable = (rootLocator, configOptions = {}) => {
     // Placeholder for the final table object
     let finalTable = null;
     // Helper factory
-    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier) => {
-        return (0, smartRow_1.default)(rowLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier);
+    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier, rowSelector) => {
+        const effectiveLocator = rowSelector
+            ? rootLocator.locator(rowSelector)
+            : rowLocator;
+        const sr = (0, smartRow_1.default)(effectiveLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier);
+        if (rowSelector)
+            sr._selfHealing = true;
+        return sr;
     };
-    const tableState = { currentPageIndex: 0 };
+    const tableState = { currentPageIndex: 0, empty: false };
     const rowFinder = new rowFinder_1.RowFinder(rootLocator, config, resolve, filterEngine, tableMapper, _makeSmart, tableState, (useBulk) => _advancePage(useBulk));
     /** Builds a full TableContext/StrategyContext with getHeaderCell, getHeaders, scrollToColumn. Set after result is created. */
     let createStrategyContext = () => ({ root: rootLocator, config, page: rootLocator.page(), resolve });
@@ -215,7 +232,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         set currentPageIndex(v) { tableState.currentPageIndex = v; },
         init: async (options) => {
             var _a;
-            if (tableMapper.isInitialized())
+            if (tableMapper.isInitialized() || tableState.empty)
                 return result;
             if (config.strategies.sorting)
                 (0, validation_1.validateSortingStrategy)(config.strategies.sorting);
@@ -223,7 +240,21 @@ const useTable = (rootLocator, configOptions = {}) => {
                 (0, validation_1.validateFillStrategy)(config.strategies.fill);
             (0, debugUtils_1.warnIfDebugInCI)(config);
             (0, debugUtils_1.logDebug)(config, 'info', 'Initializing table');
-            const map = await tableMapper.getMap(options === null || options === void 0 ? void 0 : options.timeout);
+            let map;
+            try {
+                map = await tableMapper.getMap(options === null || options === void 0 ? void 0 : options.timeout);
+            }
+            catch (headerError) {
+                if (config.emptyState) {
+                    const visible = await config.emptyState.isVisible().catch(() => false);
+                    if (visible) {
+                        tableState.empty = true;
+                        (0, debugUtils_1.logDebug)(config, 'info', 'init: header resolution failed but emptyState locator is visible — table is empty');
+                        return result;
+                    }
+                }
+                throw headerError;
+            }
             (0, debugUtils_1.logDebug)(config, 'info', `Table initialized with ${map.size} columns`, Array.from(map.keys()));
             if ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.detectCurrentPage) {
                 try {
@@ -256,9 +287,10 @@ const useTable = (rootLocator, configOptions = {}) => {
             await headerCell.scrollIntoViewIfNeeded();
         },
         getHeaders: async () => {
+            var _a;
             log("getHeaders: fetching available columns");
             const map = await tableMapper.getMap();
-            return Array.from(map.keys());
+            return [...map.keys(), ...Object.keys((_a = config.syntheticColumns) !== null && _a !== void 0 ? _a : {})];
         },
         getHeaderCell: async (columnName) => {
             log(`getHeaderCell: column="${columnName}"`);
@@ -268,25 +300,86 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw _createColumnError(columnName, map, 'header cell');
             return resolve(config.headerSelector, rootLocator).nth(idx);
         },
-        countRows: async () => {
+        countRows: async (filters, options) => {
+            var _a, _b, _c, _d;
+            if (tableState.empty)
+                return 0;
             await _autoInit();
+            const filtersRecord = (filters !== null && filters !== void 0 ? filters : {});
+            const hasFilters = Object.keys(filtersRecord).length > 0;
+            const effectiveMaxPages = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
             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));
+            const hasPagination = effectiveMaxPages > 1 && !!((pag === null || pag === void 0 ? void 0 : pag.goNext) || (pag === null || pag === void 0 ? void 0 : pag.goNextBulk));
+            const domFilters = {};
+            const overrideFilters = {};
+            const syntheticFilters = {};
+            if (hasFilters) {
+                for (const [key, value] of Object.entries(filtersRecord)) {
+                    if ((_b = config.syntheticColumns) === null || _b === void 0 ? void 0 : _b[key]) {
+                        syntheticFilters[key] = value;
+                    }
+                    else if ((_d = (_c = config.columnOverrides) === null || _c === void 0 ? void 0 : _c[key]) === null || _d === void 0 ? void 0 : _d.read) {
+                        overrideFilters[key] = value;
+                    }
+                    else {
+                        domFilters[key] = value;
+                    }
+                }
+            }
+            const hasPostFilters = Object.keys(overrideFilters).length > 0 || Object.keys(syntheticFilters).length > 0;
+            const resolveRows = () => {
+                var _a;
+                let rows = resolve(config.rowSelector, rootLocator);
+                if (Object.keys(domFilters).length > 0) {
+                    const map = tableMapper.getMapSync();
+                    if (!map)
+                        throw new Error('Initialization Error: Table map not available. Call "await table.init()" first.');
+                    rows = filterEngine.applyFilters(rows, domFilters, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, rootLocator.page(), rootLocator);
+                }
+                return rows;
+            };
+            const countPostFilterMatches = async (candidates, indices) => {
+                var _a;
+                if (!hasPostFilters)
+                    return indices.length;
+                const map = tableMapper.getMapSync();
+                if (!map)
+                    throw new Error('Initialization Error: Table map not available. Call "await table.init()" first.');
+                const exact = (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false;
+                const hasOverrides = Object.keys(overrideFilters).length > 0;
+                const hasSynthetics = Object.keys(syntheticFilters).length > 0;
+                let count = 0;
+                for (const idx of indices) {
+                    const row = candidates[idx];
+                    if (hasOverrides && !await rowFinder.matchesOverrideFilters(row, overrideFilters, map, exact))
+                        continue;
+                    if (hasSynthetics && !await rowFinder.matchesSyntheticFilters(row, syntheticFilters, map, exact))
+                        continue;
+                    count++;
+                }
+                return count;
+            };
             if (!hasPagination) {
-                log("countRows: counting rows in current viewport (no pagination)");
-                return resolve(config.rowSelector, rootLocator).count();
+                log(`countRows: counting rows in current viewport (no pagination)${hasFilters ? ` filters=${safeStringify(filtersRecord)}` : ''}`);
+                if (!hasPostFilters)
+                    return resolveRows().count();
+                const all = await resolveRows().all();
+                return countPostFilterMatches(all, all.map((_, i) => i));
             }
-            log(`countRows: paginating up to ${config.maxPages} page(s)`);
+            log(`countRows: paginating up to ${effectiveMaxPages} page(s)${hasFilters ? ` filters=${safeStringify(filtersRecord)}` : ''}`);
             const tracker = new elementTracker_1.ElementTracker('countRows');
             let total = 0;
             let pagesScanned = 1;
             let paginationError;
             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)
+                    const rowLocators = resolveRows();
+                    const newIndices = await tracker.getUnseenIndices(rowLocators);
+                    const candidates = await rowLocators.all();
+                    const matched = await countPostFilterMatches(candidates, newIndices);
+                    total += matched;
+                    log(`countRows: page ${pagesScanned} — ${matched} row(s) (running total: ${total})`);
+                    if (pagesScanned >= effectiveMaxPages)
                         break;
                     if (!await _advancePage(false))
                         break;
@@ -326,7 +419,10 @@ const useTable = (rootLocator, configOptions = {}) => {
                 await cell.bringIntoView();
                 const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[columnName];
                 if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) {
-                    return await columnOverride.read(cell);
+                    return await columnOverride.read(cell, {
+                        row, columnName, columnIndex: map.get(columnName),
+                        getCell: (name) => row.getCell(name),
+                    });
                 }
                 const text = await cell.innerText();
                 return (text || '').trim();
@@ -340,7 +436,6 @@ const useTable = (rootLocator, configOptions = {}) => {
         reset: async () => {
             var _a;
             log("Resetting table...");
-            await config.onReset(createStrategyContext());
             if ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goToFirst) {
                 log("Auto-navigating to first page...");
                 await config.strategies.pagination.goToFirst(createStrategyContext());
@@ -349,17 +444,25 @@ const useTable = (rootLocator, configOptions = {}) => {
                 log("No goToFirst strategy configured. Table may not be on page 1.");
             }
             tableState.currentPageIndex = 0;
+            tableState.empty = false;
             tableMapper.clear();
             log("Table reset complete. Calling autoInit to restore state.");
             await _autoInit();
+            await config.onReset(createStrategyContext());
         },
         revalidate: async () => {
             log("Revalidating table structure...");
             await tableMapper.remapHeaders();
+            tableState.empty = false;
             log("Table revalidated.");
         },
         getRow: (filters, options = { exact: false }) => {
             log(`getRow: filters=${safeStringify(filters)} exact=${options.exact}`);
+            const syntheticKeys = Object.keys(filters).filter(k => { var _a; return (_a = config.syntheticColumns) === null || _a === void 0 ? void 0 : _a[k]; });
+            if (syntheticKeys.length > 0) {
+                throw new Error(`getRow() cannot filter by synthetic column(s): ${syntheticKeys.join(', ')}. ` +
+                    `Use findRow() instead — synthetic columns require async evaluation.`);
+            }
             const map = tableMapper.getMapSync();
             if (!map)
                 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.');
@@ -375,6 +478,62 @@ const useTable = (rootLocator, configOptions = {}) => {
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(index);
             return _makeSmart(rowLocator, map, index);
         },
+        findRowByIndex: async (index, options) => {
+            var _a, _b;
+            log(`findRowByIndex: index=${index} options=${safeStringify(options)}`);
+            await _autoInit();
+            const map = tableMapper.getMapSync();
+            const resolveRI = config.strategies.resolveRowIndex;
+            const viewport = config.strategies.viewport;
+            // Identifying a row by its logical index requires a resolveRowIndex strategy. Without one
+            // the library can only offer render-window-relative getRowByIndex, or filter-based findRow.
+            if (!resolveRI) {
+                throw new Error(`findRowByIndex(${index}) requires a strategies.resolveRowIndex to identify rows by their logical index. ` +
+                    `Configure one (e.g. read the grid's row-index attribute), or use getRowByIndex() (current render window) / findRow(filters).`);
+            }
+            let foundSelector;
+            // The currently-mounted row whose logical index === index, if any.
+            const findMounted = async () => {
+                const rows = await resolve(config.rowSelector, rootLocator).all();
+                for (const r of rows) {
+                    const result = await resolveRI(r);
+                    if (result === undefined)
+                        continue;
+                    const normalized = (0, rowResolution_1.normalizeRowIndexResult)(result);
+                    if (normalized.index === index) {
+                        foundSelector = normalized.selector;
+                        return r;
+                    }
+                }
+                return null;
+            };
+            // 1. Already mounted (no navigation needed)?
+            let loc = await findMounted();
+            // 2. Fast path: jump straight to it via the viewport's random-access scroll.
+            if (!loc && (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow)) {
+                log(`findRowByIndex: scrolling to row ${index}`);
+                await viewport.scrollToRow(createStrategyContext(), index);
+                loc = await findMounted();
+            }
+            // 3. Fallback: advance pages (on infinite-scroll tables, a "page" is a scroll step) until
+            //    the row is reached. Bounded by maxPages so an unreachable index can't loop forever.
+            if (!loc && config.strategies.pagination) {
+                const effectiveMaxPages = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
+                let pagesScanned = 1;
+                while (!loc && pagesScanned < effectiveMaxPages) {
+                    if (!await _advancePage(false))
+                        break;
+                    pagesScanned++;
+                    loc = await findMounted();
+                }
+            }
+            if (!loc) {
+                throw new Error(`findRowByIndex(${index}): could not reach row ${index}. ` +
+                    `Ensure a viewport.scrollToRow or pagination can bring it into view (searched up to maxPages=${(_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages}).`);
+            }
+            await (0, debugUtils_1.debugDelay)(config, 'findRow');
+            return _makeSmart(loc, map, index, tableState.currentPageIndex, undefined, foundSelector);
+        },
         findRow: async (filters, options) => {
             log(`findRow: filters=${safeStringify(filters)} options=${safeStringify(options)}`);
             return rowFinder.findRow(filters, options);
@@ -384,13 +543,16 @@ const useTable = (rootLocator, configOptions = {}) => {
             return rowFinder.findRows(filters !== null && filters !== void 0 ? filters : {}, options);
         },
         isInitialized: () => {
-            const initialized = tableMapper.isInitialized();
+            const initialized = tableMapper.isInitialized() || tableState.empty;
             log(`isInitialized: ${initialized}`);
             return initialized;
         },
+        isEmpty: () => {
+            return tableState.empty;
+        },
         sorting: {
             apply: async (columnName, direction) => {
-                var _a;
+                var _a, _b, _c, _d, _e;
                 await _autoInit();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
@@ -405,13 +567,16 @@ const useTable = (rootLocator, configOptions = {}) => {
                     }
                     await config.strategies.sorting.doSort({ columnName, direction, context });
                     if ((_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isTableLoading) {
-                        const deadline = Date.now() + 10000;
+                        const timeout = (_b = config.strategies.loading.sortStabilizationTimeout) !== null && _b !== void 0 ? _b : 10000;
+                        const poll = (_c = config.strategies.loading.sortStabilizationPollInterval) !== null && _c !== void 0 ? _c : 100;
+                        const deadline = Date.now() + timeout;
                         while (Date.now() < deadline && await config.strategies.loading.isTableLoading(context)) {
-                            await rootLocator.page().waitForTimeout(100);
+                            await rootLocator.page().waitForTimeout(poll);
                         }
                     }
                     else {
-                        await rootLocator.page().waitForTimeout(200);
+                        const fallback = (_e = (_d = config.strategies.loading) === null || _d === void 0 ? void 0 : _d.sortStabilizationFallbackDelay) !== null && _e !== void 0 ? _e : 200;
+                        await rootLocator.page().waitForTimeout(fallback);
                     }
                     await (0, debugUtils_1.debugDelay)(config, 'default');
                     const newState = await config.strategies.sorting.getSortState({ columnName, context });
@@ -434,6 +599,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         // ─── Shared async row iterator ───────────────────────────────────────────
         [Symbol.asyncIterator]() {
             return __asyncGenerator(this, arguments, function* _a() {
+                var _b;
                 yield __await(_autoInit());
                 const map = tableMapper.getMapSync();
                 const effectiveMaxPages = config.maxPages;
@@ -449,7 +615,14 @@ 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, tableState.currentPageIndex, barrier), index: rowIndex, rowIndex, pageIndex: tableState.currentPageIndex });
+                            // index = visit-order counter; rowIndex = logical/data index (B-hybrid, #362).
+                            const resolved = yield __await((0, rowResolution_1.resolveLogicalRowIndex)(pageRows[idx], config, () => rowIndex));
+                            const logical = (_b = resolved === null || resolved === void 0 ? void 0 : resolved.index) !== null && _b !== void 0 ? _b : rowIndex;
+                            const sr = _makeSmart(pageRows[idx], map, logical, tableState.currentPageIndex, barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
+                            // Iterator rows share one per-page DOM snapshot (positional locators); disable
+                            // toJSON's scroll-back recovery so reading one row can't invalidate the others (#366).
+                            sr._inBatch = true;
+                            yield yield __await({ row: sr, index: rowIndex, rowIndex: logical, pageIndex: tableState.currentPageIndex });
                             rowIndex++;
                         }
                         if (pagesScanned >= effectiveMaxPages)
@@ -472,11 +645,12 @@ const useTable = (rootLocator, configOptions = {}) => {
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
                 getMap: () => tableMapper.getMapSync(),
                 advancePage: _advancePage,
-                makeSmartRow: (loc, map, idx, pageIdx, barrier) => _makeSmart(loc, map, idx, pageIdx, barrier),
+                makeSmartRow: (loc, map, idx, pageIdx, barrier, sel) => _makeSmart(loc, map, idx, pageIdx, barrier, sel),
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
                 getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
             }, callback, options);
         },
         map: async (callback, options = {}) => {
@@ -486,11 +660,12 @@ const useTable = (rootLocator, configOptions = {}) => {
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
                 getMap: () => tableMapper.getMapSync(),
                 advancePage: _advancePage,
-                makeSmartRow: (loc, map, idx, pageIdx, barrier) => _makeSmart(loc, map, idx, pageIdx, barrier),
+                makeSmartRow: (loc, map, idx, pageIdx, barrier, sel) => _makeSmart(loc, map, idx, pageIdx, barrier, sel),
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
                 getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
             }, callback, options);
         },
         toArray: async (callback, options = {}) => {
@@ -510,11 +685,12 @@ const useTable = (rootLocator, configOptions = {}) => {
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
                 getMap: () => tableMapper.getMapSync(),
                 advancePage: _advancePage,
-                makeSmartRow: (loc, map, idx, pageIdx, barrier) => _makeSmart(loc, map, idx, pageIdx, barrier),
+                makeSmartRow: (loc, map, idx, pageIdx, barrier, sel) => _makeSmart(loc, map, idx, pageIdx, barrier, sel),
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
                 getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
             }, predicate, options);
         },
         generateConfig: async () => {

package/dist/utils/mergeTableConfig.js

@@ -56,5 +56,9 @@ function mergeTableConfig(base, overrides) {
     if (base.columnOverrides || overrides.columnOverrides) {
         result.columnOverrides = Object.assign(Object.assign({}, base.columnOverrides), overrides.columnOverrides);
     }
+    // Deep-merge syntheticColumns (override keys replace, preset keys retained)
+    if (base.syntheticColumns || overrides.syntheticColumns) {
+        result.syntheticColumns = Object.assign(Object.assign({}, base.syntheticColumns), overrides.syntheticColumns);
+    }
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.18.0",
+  "version": "6.20.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",