@rickcedwhat/playwright-smart-table 6.18.0 → 6.20.0

package/dist/engine/rowFinder.d.ts

@@ -13,9 +13,13 @@ export declare class RowFinder<T = any> {
     private tableState;
     private advancePage;
     private resolve;
-    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number | undefined, tablePageIndex?: number, barrier?: NavigationBarrier) => SmartRow<T>, tableState?: {
+    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number | undefined, tablePageIndex?: number, barrier?: NavigationBarrier, rowSelector?: string) => SmartRow<T>, tableState?: {
         currentPageIndex: number;
     }, advancePage?: (useBulk: boolean) => Promise<boolean>);
+    private splitFilters;
+    static matchReadValue(readValue: string, filterValue: FilterValue, exact: boolean): boolean;
+    matchesOverrideFilters(rowLocator: Locator, overrideFilters: Record<string, FilterValue>, map: Map<string, number>, exact: boolean): Promise<boolean>;
+    matchesSyntheticFilters(rowLocator: Locator, syntheticFilters: Record<string, FilterValue>, map: Map<string, number>, exact: boolean): Promise<boolean>;
     findRow(filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
@@ -27,4 +31,15 @@ export declare class RowFinder<T = any> {
     }): Promise<SmartRowArray<T>>;
     private findRowLocator;
     private resolveRowIndex;
+    /**
+     * Fallback for findRow when no resolveRowIndex strategy is configured: find the row's
+     * position in the current DOM order in a SINGLE roundtrip. Previously this looped over
+     * every row calling elementHandle() + evaluate() per row (O(n) CDP roundtrips, and
+     * elementHandle() is soft-deprecated). We resolve the target once and let evaluateAll
+     * compare it against the full row set in the browser. The row set is resolved through the
+     * same selector/scope as everywhere else, so a string, function, or Locator rowSelector
+     * all behave identically. (#350)
+     */
+    private throwIfAmbiguous;
+    private scanDomPosition;
 }

package/dist/engine/rowFinder.js

@@ -6,6 +6,7 @@ const smartRowArray_1 = require("../utils/smartRowArray");
 const elementTracker_1 = require("../utils/elementTracker");
 const sentinel_1 = require("../utils/sentinel");
 const navigationBarrier_1 = require("../utils/navigationBarrier");
+const rowResolution_1 = require("./rowResolution");
 class RowFinder {
     constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow, tableState = { currentPageIndex: 0 }, advancePage = async () => false) {
         this.rootLocator = rootLocator;
@@ -17,6 +18,73 @@ class RowFinder {
         this.advancePage = advancePage;
         this.resolve = resolve;
     }
+    splitFilters(filters) {
+        var _a, _b, _c;
+        const domFilters = {};
+        const overrideFilters = {};
+        const syntheticFilters = {};
+        for (const [key, value] of Object.entries(filters)) {
+            if ((_a = this.config.syntheticColumns) === null || _a === void 0 ? void 0 : _a[key]) {
+                syntheticFilters[key] = value;
+            }
+            else if ((_c = (_b = this.config.columnOverrides) === null || _b === void 0 ? void 0 : _b[key]) === null || _c === void 0 ? void 0 : _c.read) {
+                overrideFilters[key] = value;
+            }
+            else {
+                domFilters[key] = value;
+            }
+        }
+        return { domFilters, overrideFilters, syntheticFilters };
+    }
+    static matchReadValue(readValue, filterValue, exact) {
+        if (typeof filterValue === 'function') {
+            throw new Error(`[SmartTable] Function filters are not supported for columns with columnOverrides.read. ` +
+                `Use a string, number, or RegExp filter instead.`);
+        }
+        if (typeof filterValue === 'string' || typeof filterValue === 'number') {
+            const target = String(filterValue);
+            return exact ? readValue === target : readValue.includes(target);
+        }
+        if (filterValue instanceof RegExp) {
+            return filterValue.test(readValue);
+        }
+        return true;
+    }
+    async matchesOverrideFilters(rowLocator, overrideFilters, map, exact) {
+        for (const [colName, filterValue] of Object.entries(overrideFilters)) {
+            const colIndex = map.get(colName);
+            if (colIndex === undefined)
+                continue;
+            const override = this.config.columnOverrides[colName];
+            const cell = this.resolve(this.config.cellSelector, rowLocator).nth(colIndex);
+            const getCell = (name) => {
+                const idx = map.get(name);
+                if (idx === undefined)
+                    throw new Error(`Column "${name}" not found`);
+                return this.resolve(this.config.cellSelector, rowLocator).nth(idx);
+            };
+            const context = {
+                row: this.makeSmartRow(rowLocator, map, undefined),
+                columnName: colName,
+                columnIndex: colIndex,
+                getCell,
+            };
+            const readValue = String(await override.read(cell, context));
+            if (!RowFinder.matchReadValue(readValue, filterValue, exact))
+                return false;
+        }
+        return true;
+    }
+    async matchesSyntheticFilters(rowLocator, syntheticFilters, map, exact) {
+        const smartRow = this.makeSmartRow(rowLocator, map, undefined);
+        for (const [colName, filterValue] of Object.entries(syntheticFilters)) {
+            const def = this.config.syntheticColumns[colName];
+            const computedValue = String(await def.compute(smartRow));
+            if (!RowFinder.matchReadValue(computedValue, filterValue, exact))
+                return false;
+        }
+        return true;
+    }
     async findRow(filters, options = {}) {
         (0, debugUtils_1.logDebug)(this.config, 'info', 'Searching for row', filters);
         await this.tableMapper.getMap();
@@ -25,8 +93,8 @@ class RowFinder {
             (0, debugUtils_1.logDebug)(this.config, 'info', 'Row found');
             await (0, debugUtils_1.debugDelay)(this.config, 'findRow');
             const map = await this.tableMapper.getMap();
-            const rowIndex = await this.resolveRowIndex(rowLocator);
-            return this.makeSmartRow(rowLocator, map, rowIndex, this.tableState.currentPageIndex);
+            const resolved = await this.resolveRowIndex(rowLocator);
+            return this.makeSmartRow(rowLocator, map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, undefined, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
         }
         (0, debugUtils_1.logDebug)(this.config, 'error', 'Row not found', filters);
         await (0, debugUtils_1.debugDelay)(this.config, 'findRow');
@@ -46,66 +114,42 @@ class RowFinder {
         (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: starting (maxPages=${effectiveMaxPages}, filters=${JSON.stringify(filtersRecord)})`);
         const tracker = new elementTracker_1.ElementTracker('findRows');
         try {
+            const { domFilters, overrideFilters, syntheticFilters } = this.splitFilters(filtersRecord);
+            const hasOverrideFilters = Object.keys(overrideFilters).length > 0;
+            const hasSyntheticFilters = Object.keys(syntheticFilters).length > 0;
             const collectMatches = async () => {
-                var _a, _b, _c, _d, _e, _f;
+                var _a, _b, _c, _d;
                 let rowLocators = this.resolve(this.config.rowSelector, this.rootLocator);
-                // Only apply filters if we have them
-                if (Object.keys(filtersRecord).length > 0) {
-                    rowLocators = this.filterEngine.applyFilters(rowLocators, filtersRecord, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page(), this.rootLocator);
+                if (Object.keys(domFilters).length > 0) {
+                    rowLocators = this.filterEngine.applyFilters(rowLocators, domFilters, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page(), this.rootLocator);
                 }
                 // Get only newly seen matched rows
                 const newIndices = await tracker.getUnseenIndices(rowLocators);
                 const currentRows = await rowLocators.all();
-                const isRowLoading = (_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isRowLoading;
-                const rawRowTimeout = (_c = this.config.strategies.loading) === null || _c === void 0 ? void 0 : _c.rowLoadingTimeout;
-                // undefined = unset (legacy skip); 0 = no wait (immediate check); >0 = wait up to N ms
-                // Non-finite values are treated as unset (defensive guard against Infinity/NaN)
-                const rowLoadingTimeout = rawRowTimeout !== undefined && Number.isFinite(rawRowTimeout) && rawRowTimeout >= 0
-                    ? rawRowTimeout
-                    : undefined;
-                const onRowLoadingTimeout = (_e = (_d = this.config.strategies.loading) === null || _d === void 0 ? void 0 : _d.onRowLoadingTimeout) !== null && _e !== void 0 ? _e : 'read-as-is';
                 let added = 0;
                 // One barrier per batch — synchronizes cell navigation across all rows in this page's results
                 const useBarrier = this.config.concurrency === 'synchronized' && newIndices.length > 1;
                 const barrier = useBarrier ? new navigationBarrier_1.NavigationBarrier(newIndices.length) : undefined;
                 for (const idx of newIndices) {
-                    // Use the configured strategy (O(1), e.g. MUI data-rowindex) when available.
-                    // Without a strategy, fall back to sequential position to avoid the O(n)
-                    // elementHandle scan that resolveRowIndex() would otherwise perform per row.
-                    const rowIndex = this.config.strategies.resolveRowIndex
-                        ? ((_f = await this.config.strategies.resolveRowIndex(currentRows[idx])) !== null && _f !== void 0 ? _f : allRows.length)
-                        : allRows.length;
-                    const smartRow = this.makeSmartRow(currentRows[idx], map, rowIndex, this.tableState.currentPageIndex, barrier);
-                    if (isRowLoading && await isRowLoading(smartRow)) {
-                        if (rowLoadingTimeout === undefined) {
-                            // No timeout configured (or invalid value) — legacy skip behavior
-                            (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: page ${this.tableState.currentPageIndex} — row skipped (isRowLoading=true, no timeout)`);
-                            barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
-                            continue;
-                        }
-                        // Wait up to rowLoadingTimeout ms (0 = one immediate re-check, no polling)
-                        (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: row ${allRows.length} — waiting up to ${rowLoadingTimeout}ms for row to load`);
-                        const deadline = Date.now() + rowLoadingTimeout;
-                        let resolved = !(await isRowLoading(smartRow)); // immediate check (handles timeout=0)
-                        while (!resolved && Date.now() < deadline) {
-                            await currentRows[idx].page().waitForTimeout(100);
-                            resolved = !(await isRowLoading(smartRow));
-                        }
-                        if (!resolved) {
-                            (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: row ${allRows.length} — still loading after ${rowLoadingTimeout}ms, action: ${onRowLoadingTimeout}`);
-                            if (onRowLoadingTimeout === 'skip') {
-                                barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
-                                continue;
-                            }
-                            if (onRowLoadingTimeout === 'throw') {
-                                barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
-                                throw new Error(`[SmartTable] Row ${allRows.length} did not finish loading within ${rowLoadingTimeout}ms`);
-                            }
-                            // 'read-as-is': fall through and add the row
-                        }
-                        else {
-                            (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: row ${allRows.length} — finished loading`);
+                    const resolved = await (0, rowResolution_1.resolveLogicalRowIndex)(currentRows[idx], this.config, () => allRows.length);
+                    const smartRow = this.makeSmartRow(currentRows[idx], map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
+                    // findRows skips a still-loading row when no timeout is configured (legacy
+                    // behavior) — see resolveRowLoading's `noTimeoutAction: 'skip'`.
+                    const loadingOutcome = await (0, rowResolution_1.resolveRowLoading)(smartRow, this.config.strategies.loading, 'skip', (msg) => (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: ${msg}`));
+                    if (loadingOutcome !== 'process') {
+                        barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
+                        if (loadingOutcome === 'throw') {
+                            throw new Error(`[SmartTable] Row ${allRows.length} did not finish loading within ${(_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.rowLoadingTimeout}ms`);
                         }
+                        continue; // 'skip'
+                    }
+                    if (hasOverrideFilters && !await this.matchesOverrideFilters(currentRows[idx], overrideFilters, map, (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false)) {
+                        barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
+                        continue;
+                    }
+                    if (hasSyntheticFilters && !await this.matchesSyntheticFilters(currentRows[idx], syntheticFilters, map, (_d = options === null || options === void 0 ? void 0 : options.exact) !== null && _d !== void 0 ? _d : false)) {
+                        barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
+                        continue;
                     }
                     allRows.push(smartRow);
                     added++;
@@ -124,7 +168,8 @@ class RowFinder {
                 const prevPage = this.tableState.currentPageIndex;
                 const didPaginate = await this.advancePage(useBulk);
                 if (!didPaginate) {
-                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: pagination returned false — end of data`);
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: pagination returned false — final scan`);
+                    await collectMatches();
                     break;
                 }
                 const pagesJumped = this.tableState.currentPageIndex - prevPage;
@@ -162,26 +207,37 @@ class RowFinder {
                 }
             }
             const allRows = this.resolve(this.config.rowSelector, this.rootLocator);
-            const matchedRows = this.filterEngine.applyFilters(allRows, filters, map, options.exact || false, this.rootLocator.page(), this.rootLocator);
-            const count = await matchedRows.count();
-            (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Found ${count} matches.`);
-            if (count > 1) {
-                const sampleData = [];
-                try {
-                    const firstFewRows = await matchedRows.all();
-                    const sampleCount = Math.min(firstFewRows.length, 3);
-                    for (let i = 0; i < sampleCount; i++) {
-                        const rowData = await this.makeSmartRow(firstFewRows[i], map, 0, this.tableState.currentPageIndex).toJSON();
-                        sampleData.push(JSON.stringify(rowData));
-                    }
-                }
-                catch (e) { }
-                const sampleMsg = sampleData.length > 0 ? `\nSample matching rows:\n${sampleData.map((d, i) => `  ${i + 1}. ${d}`).join('\n')}` : '';
-                throw new Error(`Ambiguous Row: Found ${count} rows matching ${JSON.stringify(filters)} on page ${this.tableState.currentPageIndex}. ` +
-                    `Expected exactly one match. Try adding more filters to make your query unique.${sampleMsg}`);
+            const { domFilters, overrideFilters, syntheticFilters } = this.splitFilters(filters);
+            const hasPostFilters = Object.keys(overrideFilters).length > 0 || Object.keys(syntheticFilters).length > 0;
+            let matchedRows = allRows;
+            if (Object.keys(domFilters).length > 0) {
+                matchedRows = this.filterEngine.applyFilters(allRows, domFilters, map, options.exact || false, this.rootLocator.page(), this.rootLocator);
+            }
+            if (!hasPostFilters) {
+                const count = await matchedRows.count();
+                (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Found ${count} matches.`);
+                if (count > 1)
+                    await this.throwIfAmbiguous(await matchedRows.all(), filters, map);
+                if (count === 1)
+                    return matchedRows.first();
+            }
+            else {
+                const candidates = await matchedRows.all();
+                (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: ${candidates.length} DOM candidate(s), post-filtering with override/synthetic columns`);
+                const results = await Promise.all(candidates.map(async (c) => {
+                    if (Object.keys(overrideFilters).length > 0 && !await this.matchesOverrideFilters(c, overrideFilters, map, options.exact || false))
+                        return false;
+                    if (Object.keys(syntheticFilters).length > 0 && !await this.matchesSyntheticFilters(c, syntheticFilters, map, options.exact || false))
+                        return false;
+                    return true;
+                }));
+                const postFilterMatches = candidates.filter((_, i) => results[i]);
+                (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: ${postFilterMatches.length} match(es) after post-filter`);
+                if (postFilterMatches.length > 1)
+                    await this.throwIfAmbiguous(postFilterMatches, filters, map);
+                if (postFilterMatches.length === 1)
+                    return postFilterMatches[0];
             }
-            if (count === 1)
-                return matchedRows.first();
             if (pagesScanned < effectiveMaxPages) {
                 (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Not found. Attempting pagination...`);
                 // Default to single-step goNext; bulk is opt-in via useBulkPagination: true (#349).
@@ -197,25 +253,42 @@ class RowFinder {
                     continue;
                 }
                 else {
-                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Pagination failed (end of data).`);
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: pagination returned false — final scan`);
+                    pagesScanned = effectiveMaxPages;
+                    continue;
                 }
             }
             return null;
         }
     }
-    async resolveRowIndex(rowLocator) {
-        if (this.config.strategies.resolveRowIndex) {
-            const result = await this.config.strategies.resolveRowIndex(rowLocator);
-            if (result !== undefined)
-                return result;
-            // Strategy returned undefined — fall through to DOM scan below.
+    resolveRowIndex(rowLocator) {
+        // Shared resolver: resolveRowIndex strategy first, else the DOM-position fallback.
+        return (0, rowResolution_1.resolveLogicalRowIndex)(rowLocator, this.config, () => this.scanDomPosition(rowLocator));
+    }
+    /**
+     * Fallback for findRow when no resolveRowIndex strategy is configured: find the row's
+     * position in the current DOM order in a SINGLE roundtrip. Previously this looped over
+     * every row calling elementHandle() + evaluate() per row (O(n) CDP roundtrips, and
+     * elementHandle() is soft-deprecated). We resolve the target once and let evaluateAll
+     * compare it against the full row set in the browser. The row set is resolved through the
+     * same selector/scope as everywhere else, so a string, function, or Locator rowSelector
+     * all behave identically. (#350)
+     */
+    async throwIfAmbiguous(rows, filters, map) {
+        const sampleData = [];
+        try {
+            const sampleCount = Math.min(rows.length, 3);
+            for (let i = 0; i < sampleCount; i++) {
+                const rowData = await this.makeSmartRow(rows[i], map, 0, this.tableState.currentPageIndex).toJSON();
+                sampleData.push(JSON.stringify(rowData));
+            }
         }
-        // Fallback: find the row's position in the current DOM order in a SINGLE roundtrip.
-        // Previously this looped over every row calling elementHandle() + evaluate() per row
-        // (O(n) CDP roundtrips, and elementHandle() is soft-deprecated). We now resolve the
-        // target once and let evaluateAll compare it against the full row set in the browser.
-        // The row set is resolved through the same selector/scope as everywhere else, so a
-        // string, function, or Locator rowSelector all behave identically. (#350)
+        catch (e) { }
+        const sampleMsg = sampleData.length > 0 ? `\nSample matching rows:\n${sampleData.map((d, i) => `  ${i + 1}. ${d}`).join('\n')}` : '';
+        throw new Error(`Ambiguous Row: Found ${rows.length} rows matching ${JSON.stringify(filters)} on page ${this.tableState.currentPageIndex}. ` +
+            `Expected exactly one match. Try adding more filters to make your query unique.${sampleMsg}`);
+    }
+    async scanDomPosition(rowLocator) {
         const targetHandle = await rowLocator.elementHandle();
         if (!targetHandle)
             return undefined;

package/dist/engine/rowResolution.d.ts

@@ -0,0 +1,35 @@
+import type { Locator } from '@playwright/test';
+import type { FinalTableConfig, LoadingStrategy, RowIndexResult, SmartRow } from '../types';
+/** Normalized result from resolveRowIndex — always has `.index`, optionally `.selector`. */
+export interface ResolvedRowIndex {
+    index: number;
+    selector?: string;
+}
+/** Extract the numeric index from a {@link RowIndexResult}. */
+export declare function normalizeRowIndexResult(result: RowIndexResult): ResolvedRowIndex;
+/**
+ * Single source of truth for "what is this row's logical index?" (#362 consolidation).
+ *
+ * Uses the configured `resolveRowIndex` strategy when present (e.g. MUI's `data-rowindex`);
+ * otherwise, and when the strategy returns `undefined`, defers to the caller-provided
+ * `fallback` — a running counter for iteration/`findRows`, or a DOM-position scan for `findRow`.
+ *
+ * Returns a {@link ResolvedRowIndex} with the numeric index and, when the strategy provides
+ * one, a CSS selector for building a self-healing row locator.
+ */
+export declare function resolveLogicalRowIndex(row: Locator, config: Pick<FinalTableConfig, 'strategies'>, fallback: () => number | undefined | Promise<number | undefined>): Promise<ResolvedRowIndex | undefined>;
+/** What the caller should do with a row after checking its loading state. */
+export type RowLoadingOutcome = 'process' | 'skip' | 'throw';
+/**
+ * Single source of truth for the per-row loading wait (#362 consolidation).
+ *
+ * Collapses the two near-identical blocks in `findRows` (RowFinder) and `runMap`
+ * (tableIteration). The only real difference between the callers is the behavior when no
+ * `rowLoadingTimeout` is configured: `findRows` skips a still-loading row (`noTimeoutAction:
+ * 'skip'`), while `map`/`forEach`/`filter` process it as-is (`'process'`) — and map, in that
+ * case, never even probes `isRowLoading`. Both are preserved exactly.
+ *
+ * The helper never throws and never touches the navigation barrier; it returns a decision so
+ * each caller keeps its own barrier bookkeeping and error message.
+ */
+export declare function resolveRowLoading(row: SmartRow, loading: LoadingStrategy | undefined, noTimeoutAction: 'skip' | 'process', log?: (msg: string) => void): Promise<RowLoadingOutcome>;

package/dist/engine/rowResolution.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeRowIndexResult = normalizeRowIndexResult;
+exports.resolveLogicalRowIndex = resolveLogicalRowIndex;
+exports.resolveRowLoading = resolveRowLoading;
+/** Extract the numeric index from a {@link RowIndexResult}. */
+function normalizeRowIndexResult(result) {
+    return typeof result === 'number' ? { index: result } : result;
+}
+/**
+ * Single source of truth for "what is this row's logical index?" (#362 consolidation).
+ *
+ * Uses the configured `resolveRowIndex` strategy when present (e.g. MUI's `data-rowindex`);
+ * otherwise, and when the strategy returns `undefined`, defers to the caller-provided
+ * `fallback` — a running counter for iteration/`findRows`, or a DOM-position scan for `findRow`.
+ *
+ * Returns a {@link ResolvedRowIndex} with the numeric index and, when the strategy provides
+ * one, a CSS selector for building a self-healing row locator.
+ */
+async function resolveLogicalRowIndex(row, config, fallback) {
+    const strategy = config.strategies.resolveRowIndex;
+    if (strategy) {
+        const resolved = await strategy(row);
+        if (resolved !== undefined)
+            return normalizeRowIndexResult(resolved);
+    }
+    const fb = await fallback();
+    return fb !== undefined ? { index: fb } : undefined;
+}
+/**
+ * Single source of truth for the per-row loading wait (#362 consolidation).
+ *
+ * Collapses the two near-identical blocks in `findRows` (RowFinder) and `runMap`
+ * (tableIteration). The only real difference between the callers is the behavior when no
+ * `rowLoadingTimeout` is configured: `findRows` skips a still-loading row (`noTimeoutAction:
+ * 'skip'`), while `map`/`forEach`/`filter` process it as-is (`'process'`) — and map, in that
+ * case, never even probes `isRowLoading`. Both are preserved exactly.
+ *
+ * The helper never throws and never touches the navigation barrier; it returns a decision so
+ * each caller keeps its own barrier bookkeeping and error message.
+ */
+async function resolveRowLoading(row, loading, noTimeoutAction, log) {
+    var _a;
+    const isRowLoading = loading === null || loading === void 0 ? void 0 : loading.isRowLoading;
+    if (!isRowLoading)
+        return 'process';
+    const rawTimeout = loading === null || loading === void 0 ? void 0 : loading.rowLoadingTimeout;
+    // undefined = unset (legacy skip / process-as-is); 0 = one immediate re-check; >0 = poll up to N ms.
+    // Non-finite values are treated as unset (defensive guard against Infinity/NaN).
+    const timeout = rawTimeout !== undefined && Number.isFinite(rawTimeout) && rawTimeout >= 0
+        ? rawTimeout
+        : undefined;
+    // map's fast path: with no timeout and a process-default, it never probes isRowLoading.
+    if (timeout === undefined && noTimeoutAction === 'process')
+        return 'process';
+    if (!(await isRowLoading(row)))
+        return 'process';
+    // Row is loading with no timeout configured → legacy skip (findRows).
+    if (timeout === undefined)
+        return 'skip';
+    log === null || log === void 0 ? void 0 : log(`row ${row.rowIndex} — waiting up to ${timeout}ms for row to load`);
+    const deadline = Date.now() + timeout;
+    let resolved = !(await isRowLoading(row)); // immediate check (handles timeout=0)
+    while (!resolved && Date.now() < deadline) {
+        // Page accessed lazily (only while actually polling), matching the pre-refactor code.
+        await row.page().waitForTimeout(100);
+        resolved = !(await isRowLoading(row));
+    }
+    if (resolved)
+        return 'process';
+    const onTimeout = (_a = loading === null || loading === void 0 ? void 0 : loading.onRowLoadingTimeout) !== null && _a !== void 0 ? _a : 'read-as-is';
+    log === null || log === void 0 ? void 0 : log(`row ${row.rowIndex} — still loading after ${timeout}ms, action: ${onTimeout}`);
+    if (onTimeout === 'skip')
+        return 'skip';
+    if (onTimeout === 'throw')
+        return 'throw';
+    return 'process'; // 'read-as-is'
+}

package/dist/engine/tableIteration.d.ts

@@ -1,5 +1,5 @@
 import type { Locator, Page } from '@playwright/test';
-import type { SmartRow, RowIterationContext, RowIterationOptions } from '../types';
+import type { SmartRow, RowIterationContext, RowIterationOptions, TableContext } from '../types';
 import type { FinalTableConfig } from '../types';
 import type { SmartRowArray } from '../utils/smartRowArray';
 import { NavigationBarrier } from '../utils/navigationBarrier';
@@ -7,11 +7,13 @@ export interface TableIterationEnv<T = any> {
     getRowLocators: () => Locator;
     getMap: () => Map<string, number>;
     advancePage: (useBulk: boolean) => Promise<boolean>;
-    makeSmartRow: (rowLocator: Locator, map: Map<string, number>, rowIndex: number, tablePageIndex?: number, barrier?: NavigationBarrier) => SmartRow<T>;
+    makeSmartRow: (rowLocator: Locator, map: Map<string, number>, rowIndex: number, tablePageIndex?: number, barrier?: NavigationBarrier, rowSelector?: string) => SmartRow<T>;
     createSmartRowArray: (rows: SmartRow<T>[]) => SmartRowArray<T>;
     config: FinalTableConfig<T>;
     getPage: () => Page;
     getCurrentPageIndex: () => number;
+    /** Builds a TableContext for strategy calls (e.g. the viewport visible-row oracle). */
+    getContext: () => TableContext;
 }
 /** Delegates to {@link runMap}; void results are discarded. */
 export declare function runForEach<T>(env: TableIterationEnv<T>, callback: (ctx: RowIterationContext<T>) => void | Promise<void>, options?: RowIterationOptions): Promise<void>;