@rickcedwhat/playwright-smart-table 6.19.0 → 6.20.1

package/dist/types.d.ts

@@ -10,6 +10,15 @@ import type { SmartRowArray } from './utils/smartRowArray';
  * headerSelector: (root) => root.locator('[role="columnheader"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
+/**
+ * Return type for `resolveRowIndex`. A plain number gives the logical index only;
+ * `{ index, selector }` additionally provides a CSS selector the library uses to
+ * build a self-healing row locator that survives virtual-scroll DOM recycling.
+ */
+export type RowIndexResult = number | {
+    index: number;
+    selector: string;
+};
 /**
  * Value used to filter rows.
  * - string/number/RegExp: filter by text content of the cell.
@@ -281,6 +290,12 @@ export type SmartRow<T = any> = Locator & {
      * );
      */
     smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
+    /**
+     * Get the resolved value of any column — real, override, or synthetic.
+     * @param column - Column name (case-sensitive)
+     * @returns The column value as a string
+     */
+    getValue(column: string): Promise<string>;
     /**
      * Returns whether the row exists in the DOM (i.e. is not a sentinel row).
      */
@@ -427,6 +442,9 @@ export interface ColumnOverrideReadContext {
      */
     getCell: (columnName: string) => Locator;
 }
+export interface SyntheticColumnDef<T = any> {
+    compute: (row: SmartRow<T>) => Promise<string | number> | string | number;
+}
 export interface ColumnOverride<TValue = any> {
     /**
      * How to extract the value from the cell.
@@ -512,6 +530,12 @@ export interface LoadingStrategy {
      * Defaults to 'read-as-is' when cellLoadingTimeout is set.
      */
     onCellLoadingTimeout?: 'skip' | 'read-as-is' | 'throw' | ((cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<string>);
+    /** Max ms to wait for sort stabilization when isTableLoading is set. @default 10000 */
+    sortStabilizationTimeout?: number;
+    /** Polling interval (ms) while waiting for sort stabilization. @default 100 */
+    sortStabilizationPollInterval?: number;
+    /** Fallback delay (ms) after sort when no isTableLoading is configured. @default 200 */
+    sortStabilizationFallbackDelay?: number;
 }
 /**
  * Organized container for all table interaction strategies.
@@ -559,14 +583,20 @@ export interface TableStrategies {
      *
      * Return `undefined` to fall back to DOM position.
      *
+     * When the index maps to a DOM attribute, return `{ index, selector }` instead of
+     * a plain number. The library uses the CSS selector to build a **self-healing row
+     * locator** that re-queries the DOM on every action — surviving virtual-scroll
+     * recycling for `getCell`, `smartFill`, and `toJSON` without manual re-pinning.
+     *
      * @example
-     * // MUI DataGrid: read the global monotone counter from the attribute
+     * // MUI DataGrid: self-healing via data-rowindex attribute
      * resolveRowIndex: async (row) => {
      *   const v = await row.getAttribute('data-rowindex').catch(() => null);
-     *   return v !== null && !isNaN(Number(v)) ? Number(v) : undefined;
+     *   if (v === null || isNaN(Number(v))) return undefined;
+     *   return { index: Number(v), selector: `[data-rowindex="${v}"]` };
      * }
      */
-    resolveRowIndex?: (row: Locator) => Promise<number | undefined>;
+    resolveRowIndex?: (row: Locator) => Promise<RowIndexResult | undefined>;
     /**
      * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
      * Braintrust-style grids where both rows and columns are virtualized simultaneously).
@@ -604,7 +634,7 @@ export interface TableConfig<T = any> {
     autoScroll?: boolean;
     /** Debug options for development and troubleshooting */
     debug?: DebugConfig;
-    /** Reset hook */
+    /** Hook called after reset completes (after goToFirst, cache clear, and autoInit). */
     onReset?: (context: TableContext) => Promise<void>;
     /** All interaction strategies */
     strategies?: TableStrategies;
@@ -613,6 +643,13 @@ export interface TableConfig<T = any> {
      * Overrides both default extraction (toJSON) and filling (smartFill) logic.
      */
     columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
+    /**
+     * Computed columns with no DOM presence. Each key becomes a virtual column name
+     * available in `toJSON()`, `getValue()`, and `findRow()`/`findRows()` filters.
+     * The `compute` function receives the full SmartRow and must only read real or
+     * override columns (no chaining between synthetics).
+     */
+    syntheticColumns?: Record<string, SyntheticColumnDef<T>>;
     /**
      * Locator for an empty-state element that replaces the table when there are no results.
      * If header resolution fails during init() and this locator is visible, init() succeeds
@@ -790,10 +827,14 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     scrollToColumn: (columnName: string) => Promise<void>;
     /**
-     * Counts the number of rows currently on the page.
-     * Does not paginate.
+     * Counts the number of rows, optionally filtered.
+     * Without arguments, counts all rows. With filters, counts only matching rows.
+     * Paginates when pagination is configured.
      */
-    countRows: () => Promise<number>;
+    countRows: (filters?: Record<string, FilterValue>, options?: {
+        exact?: boolean;
+        maxPages?: number;
+    }) => Promise<number>;
     /**
      * Iterates over rows and extracts the value of a single column.
      * More efficient than map + toJSON for single-column extraction.
@@ -808,7 +849,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;
     /**
-     * Resets the table state (clears cache, flags) and invokes the onReset strategy.
+     * Resets the table: calls goToFirst (if configured), clears cache, re-inits headers, then calls onReset.
      */
     reset: () => Promise<void>;
     /**

package/dist/useTable.js

@@ -145,8 +145,14 @@ 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, empty: false };
     const rowFinder = new rowFinder_1.RowFinder(rootLocator, config, resolve, filterEngine, tableMapper, _makeSmart, tableState, (useBulk) => _advancePage(useBulk));
@@ -281,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}"`);
@@ -293,27 +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;
@@ -370,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());
@@ -383,6 +448,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             tableMapper.clear();
             log("Table reset complete. Calling autoInit to restore state.");
             await _autoInit();
+            await config.onReset(createStrategyContext());
         },
         revalidate: async () => {
             log("Revalidating table structure...");
@@ -392,6 +458,11 @@ const useTable = (rootLocator, configOptions = {}) => {
         },
         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.');
@@ -420,12 +491,19 @@ const useTable = (rootLocator, configOptions = {}) => {
                 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) {
-                    if ((await resolveRI(r)) === index)
+                    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;
             };
@@ -454,7 +532,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     `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);
+            return _makeSmart(loc, map, index, tableState.currentPageIndex, undefined, foundSelector);
         },
         findRow: async (filters, options) => {
             log(`findRow: filters=${safeStringify(filters)} options=${safeStringify(options)}`);
@@ -474,7 +552,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         },
         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.');
@@ -489,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 });
@@ -535,8 +616,9 @@ const useTable = (rootLocator, configOptions = {}) => {
                         const barrier = new navigationBarrier_1.NavigationBarrier(newIndices.length);
                         for (const idx of newIndices) {
                             // index = visit-order counter; rowIndex = logical/data index (B-hybrid, #362).
-                            const logical = (_b = yield __await((0, rowResolution_1.resolveLogicalRowIndex)(pageRows[idx], config, () => rowIndex))) !== null && _b !== void 0 ? _b : rowIndex;
-                            const sr = _makeSmart(pageRows[idx], map, logical, tableState.currentPageIndex, barrier);
+                            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;
@@ -563,7 +645,7 @@ 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(),
@@ -578,7 +660,7 @@ 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(),
@@ -603,7 +685,7 @@ 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(),

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.19.0",
+  "version": "6.20.1",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -110,6 +110,11 @@
   "peerDependencies": {
     "@playwright/test": "^1.40.0"
   },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@commitlint/cli": "^21.0.0",
     "@commitlint/config-conventional": "^21.0.0",