@rickcedwhat/playwright-smart-table 6.20.1-next.720a2e5 → 6.20.1-next.a5f5df2

package/dist/types.d.ts

@@ -269,6 +269,9 @@ export type SmartRow<T = any> = Locator & {
      * Scrolls/paginates to bring this row into view.
      * Works when row position metadata is known (e.g., from getRowByIndex, findRow,
      * findRows, filter, or async iteration).
+     *
+     * Prefers `strategies.viewport.scrollToRow` when configured; otherwise falls back to
+     * Playwright `scrollIntoViewIfNeeded()`.
      * @throws Error if row position metadata is unknown
      */
     bringIntoView(): Promise<void>;
@@ -292,6 +295,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.
+     *
+     * When `strategies.viewport` or `strategies.navigation` is configured, runs the same
+     * cell-navigation pipeline as `toJSON` / `getCell().bringIntoView()` so off-screen
+     * virtualized cells are mounted before reading. Without those strategies, reads the
+     * current DOM cell (Playwright auto-wait).
+     *
      * @param column - Column name (case-sensitive)
      * @returns The column value as a string
      */
@@ -403,6 +412,7 @@ export interface PaginationPrimitives {
 }
 export type PaginationStrategy = PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
+export type ContentReadyStrategy = (row: Locator, page: Page) => Promise<void>;
 export type FillStrategy = (options: {
     row: SmartRow;
     columnName: string;
@@ -467,6 +477,7 @@ export interface ColumnOverride<TValue = any> {
 import { HeaderStrategy } from './strategies/headers';
 export type { HeaderStrategy } from './strategies/headers';
 import { NavigationPrimitives } from './strategies/columns';
+export type { NavigationPrimitives, CellNavigationStrategy } from './strategies/columns';
 /**
  * Strategy to resolve column names (string or regex) to their index.
  */
@@ -597,6 +608,23 @@ export interface TableStrategies {
      * }
      */
     resolveRowIndex?: (row: Locator) => Promise<RowIndexResult | undefined>;
+    /**
+     * Waits until a row's content has stabilized before cloning in
+     * `toJSON({ atomic: true })`. Needed for recycling virtualizers where the
+     * framework updates element positions synchronously but renders cell content
+     * asynchronously (e.g. react-window, react-virtuoso with React concurrent mode).
+     *
+     * Without this, the clone captures stale content from the previous occupant of the
+     * DOM slot — the element is at the correct position but React hasn't re-rendered yet.
+     *
+     * Use `Strategies.ContentReady.textStable()` for the built-in text-polling strategy.
+     *
+     * @example
+     * strategies: {
+     *   contentReady: Strategies.ContentReady.textStable({ timeout: 500 }),
+     * }
+     */
+    contentReady?: ContentReadyStrategy;
     /**
      * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
      * Braintrust-style grids where both rows and columns are virtualized simultaneously).
@@ -657,6 +685,9 @@ export interface TableConfig<T = any> {
      */
     emptyState?: Locator;
 }
+/**
+ * @internal Resolved config after defaults are applied. Prefer {@link TableConfig} in public code.
+ */
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
     headerSelector: string | ((root: Locator) => Locator);
     rowSelector: string;
@@ -725,6 +756,11 @@ export type RowIterationOptions = {
      */
     useBulkPagination?: boolean;
 };
+/**
+ * Result of {@link useTable}. Implements `AsyncIterable` — `for await (const { row } of table)`
+ * uses the same page-walk as `map` / `forEach` (`scanPages` + runMap): overscan, loading,
+ * dedupe, and EOF final scan (#427).
+ */
 export interface TableResult<T = any> extends AsyncIterable<{
     row: SmartRow<T>;
     rowIndex: number;
@@ -762,6 +798,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * @note The sync path cannot compute a real `rowIndex`, so the returned SmartRow's
      * `rowIndex` is `undefined` (virtual-scroll positioning via `bringIntoView()` is limited).
      * Use `findRow()` (async) when you need a row with an accurate `rowIndex`.
+     * @note Cannot filter by `syntheticColumns` or `columnOverrides.read` keys — those need
+     * async evaluation via `findRow()` / `findRows()`. DOM filters use `strategies.getCellLocator`
+     * when configured (column-virtualized grids), otherwise `cellSelector` + column index.
      */
     getRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
@@ -823,7 +862,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
         useBulkPagination?: boolean;
     }) => Promise<SmartRowArray<T>>;
     /**
-     * Navigates to a specific column using the configured CellNavigationStrategy.
+     * Resolves the named column and scrolls it into view.
+     * Prefers `strategies.viewport.scrollToColumn` when configured; otherwise scrolls the
+     * header cell via Playwright `scrollIntoViewIfNeeded()`.
      */
     scrollToColumn: (columnName: string) => Promise<void>;
     /**
@@ -843,6 +884,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;
     /**
+     * @deprecated Use `mapColumn` (or `map`) instead. Will be removed in v7.0.0.
      * Iterates over rows and extracts the value of a single column as strings.
      * @param columnName - The name of the column to extract
      * @param options - Iteration options

package/dist/useTable.js

@@ -28,10 +28,10 @@ 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 scanPages_1 = require("./engine/scanPages");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
 const elementTracker_1 = require("./utils/elementTracker");
-const navigationBarrier_1 = require("./utils/navigationBarrier");
 // Helper to safely serialize objects containing functions for logging
 const safeStringify = (obj) => {
     try {
@@ -145,11 +145,11 @@ const useTable = (rootLocator, configOptions = {}) => {
     // Placeholder for the final table object
     let finalTable = null;
     // Helper factory
-    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier, rowSelector) => {
+    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier, rowSelector, renderWindowPosition = false) => {
         const effectiveLocator = rowSelector
             ? rootLocator.locator(rowSelector)
             : rowLocator;
-        const sr = (0, smartRow_1.default)(effectiveLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier);
+        const sr = (0, smartRow_1.default)(effectiveLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier, renderWindowPosition);
         if (rowSelector)
             sr._selfHealing = true;
         return sr;
@@ -277,12 +277,19 @@ const useTable = (rootLocator, configOptions = {}) => {
             return result;
         },
         scrollToColumn: async (columnName) => {
+            var _a;
             log(`scrollToColumn: column="${columnName}"`);
             const map = await tableMapper.getMap();
             const idx = map.get(columnName);
             if (idx === undefined)
                 throw _createColumnError(columnName, map);
-            // Use header cell for scrolling
+            // Prefer viewport strategy when configured (#430). Raw scrollIntoViewIfNeeded on a
+            // header can shift Y and evict virtualized rows; viewport.scrollToColumn is X-aware.
+            const viewportScroll = (_a = config.strategies.viewport) === null || _a === void 0 ? void 0 : _a.scrollToColumn;
+            if (viewportScroll) {
+                await viewportScroll(createStrategyContext(), idx);
+                return;
+            }
             const headerCell = resolve(config.headerSelector, rootLocator).nth(idx);
             await headerCell.scrollIntoViewIfNeeded();
         },
@@ -381,19 +388,34 @@ const useTable = (rootLocator, configOptions = {}) => {
             let pagesScanned = 1;
             let paginationError;
             try {
-                while (true) {
+                const scanned = await (0, scanPages_1.scanPages)({
+                    advancePage: _advancePage,
+                    getCurrentPageIndex: () => tableState.currentPageIndex,
+                    config,
+                    waitForReady: async () => {
+                        if (!isTableLoading)
+                            return;
+                        const ctx = createStrategyContext();
+                        while (await isTableLoading(ctx)) {
+                            log('countRows: table is loading... waiting');
+                            await rootLocator.page().waitForTimeout(200);
+                        }
+                    },
+                }, async ({ pagesScanned: pageNum }) => {
                     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;
-                    pagesScanned++;
-                }
+                    log(`countRows: page ${pageNum} — ${matched} row(s) (running total: ${total})`);
+                    return 'continue';
+                }, {
+                    maxPages: effectiveMaxPages,
+                    useBulk: false,
+                    label: 'countRows',
+                    finalScanOnEof: true,
+                });
+                pagesScanned = scanned.pagesScanned;
             }
             catch (e) {
                 paginationError = e;
@@ -437,6 +459,10 @@ const useTable = (rootLocator, configOptions = {}) => {
                 return (text || '').trim();
             }, options);
         },
+        /**
+         * @deprecated Use `mapColumn` (or `map`) instead. Will be removed in v7.0.0.
+         * Iterates over rows and extracts the value of a single column as strings.
+         */
         getColumnValues: async (columnName, options = {}) => {
             log(`getColumnValues: column="${columnName}" options=${safeStringify(options)}`);
             const values = await result.mapColumn(columnName, options);
@@ -472,6 +498,11 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw new Error(`getRow() cannot filter by synthetic column(s): ${syntheticKeys.join(', ')}. ` +
                     `Use findRow() instead — synthetic columns require async evaluation.`);
             }
+            const overrideKeys = Object.keys(filters).filter(k => { var _a, _b; return (_b = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[k]) === null || _b === void 0 ? void 0 : _b.read; });
+            if (overrideKeys.length > 0) {
+                throw new Error(`getRow() cannot filter by columnOverrides.read column(s): ${overrideKeys.join(', ')}. ` +
+                    `Use findRow() instead — override 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.');
@@ -485,7 +516,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             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.');
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(index);
-            return _makeSmart(rowLocator, map, index);
+            return _makeSmart(rowLocator, map, index, undefined, undefined, undefined, true);
         },
         findRowByIndex: async (index, options) => {
             var _a, _b;
@@ -606,43 +637,65 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
         },
         // ─── Shared async row iterator ───────────────────────────────────────────
+        /**
+         * Streams rows using the same page-walk + collection path as `map` / `forEach`
+         * (`scanPages` + runMap): overscan filtering, loading-before-dedupe, EOF final
+         * scan, and config dedupe. Concurrency is sequential so yields stay ordered. (#427)
+         */
         [Symbol.asyncIterator]() {
             return __asyncGenerator(this, arguments, function* _a() {
-                var _b;
                 yield __await(_autoInit());
-                const map = tableMapper.getMapSync();
-                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})`);
+                log(`iterator: starting via runMap (maxPages=${config.maxPages})`);
+                const queue = [];
+                let notify;
+                let release;
+                let finished = false;
+                let cancelled = false;
+                let runError;
+                const wake = () => {
+                    notify === null || notify === void 0 ? void 0 : notify();
+                    notify = undefined;
+                };
+                const runPromise = (0, tableIteration_1.runMap)({
+                    getRowLocators: () => resolve(config.rowSelector, rootLocator),
+                    getMap: () => tableMapper.getMapSync(),
+                    advancePage: _advancePage,
+                    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(),
+                }, async (ctx) => {
+                    queue.push({
+                        row: ctx.row,
+                        index: ctx.index,
+                        rowIndex: ctx.rowIndex,
+                        pageIndex: ctx.pageIndex,
+                    });
+                    wake();
+                    await new Promise((resolve) => { release = resolve; });
+                    if (cancelled)
+                        ctx.stop();
+                }, { concurrency: 'sequential' }, 'iterator').then(() => { finished = true; wake(); }, (err) => { runError = err; finished = true; wake(); });
                 try {
-                    let rowIndex = 0;
-                    let pagesScanned = 1;
-                    while (true) {
-                        const rowLocators = resolve(config.rowSelector, rootLocator);
-                        const newIndices = yield __await(tracker.getUnseenIndices(rowLocators));
-                        const pageRows = yield __await(rowLocators.all());
-                        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 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++;
+                    while (!finished || queue.length > 0) {
+                        if (queue.length === 0) {
+                            yield __await(new Promise((resolve) => { notify = resolve; }));
+                        }
+                        while (queue.length > 0) {
+                            yield yield __await(queue.shift());
+                            release === null || release === void 0 ? void 0 : release();
+                            release = undefined;
                         }
-                        if (pagesScanned >= effectiveMaxPages)
-                            break;
-                        if (!(yield __await(_advancePage(useBulk))))
-                            break;
-                        pagesScanned++;
+                        if (runError)
+                            throw runError;
                     }
                 }
                 finally {
-                    yield __await(tracker.cleanup(rootLocator.page()));
+                    cancelled = true;
+                    release === null || release === void 0 ? void 0 : release();
+                    yield __await(runPromise.catch(() => { }));
                 }
             });
         },

package/dist/utils/resolveCellLocator.d.ts

@@ -0,0 +1,35 @@
+import type { Locator, Page } from '@playwright/test';
+import type { FinalTableConfig, Selector } from '../types';
+/**
+ * Resolve a cell locator for a concrete row — prefers `strategies.getCellLocator`,
+ * otherwise `cellSelector` + `.nth(columnIndex)`.
+ */
+export declare function resolveCellLocator(args: {
+    config: FinalTableConfig;
+    resolve: (selector: Selector, parent: Locator | Page) => Locator;
+    row: Locator;
+    root: Locator;
+    columnName: string;
+    columnIndex: number;
+    rowIndex?: number;
+    page?: Page;
+}): Locator;
+/**
+ * Cell locator for Playwright `rows.filter({ has })`.
+ *
+ * When `getCellLocator` is set, pass `page.locator(':scope')` as the row so the
+ * strategy's `row.locator(...)` chain stays relative to each candidate row under
+ * `filter({ has })`. Using the rows collection or a document-rooted parent nests
+ * the row selector and matches nothing.
+ *
+ * Without `getCellLocator`, keeps the historical page-scoped `cellSelector.nth(i)`
+ * template that Playwright re-bases into each row.
+ */
+export declare function resolveCellLocatorForFilter(args: {
+    config: FinalTableConfig;
+    resolve: (selector: Selector, parent: Locator | Page) => Locator;
+    page: Page;
+    root?: Locator;
+    columnName: string;
+    columnIndex: number;
+}): Locator;

package/dist/utils/resolveCellLocator.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCellLocator = resolveCellLocator;
+exports.resolveCellLocatorForFilter = resolveCellLocatorForFilter;
+/**
+ * Resolve a cell locator for a concrete row — prefers `strategies.getCellLocator`,
+ * otherwise `cellSelector` + `.nth(columnIndex)`.
+ */
+function resolveCellLocator(args) {
+    var _a, _b;
+    const { config, resolve, row, root, columnName, columnIndex, rowIndex } = args;
+    const page = (_a = args.page) !== null && _a !== void 0 ? _a : root.page();
+    if ((_b = config.strategies) === null || _b === void 0 ? void 0 : _b.getCellLocator) {
+        return config.strategies.getCellLocator({
+            row,
+            root,
+            columnName,
+            columnIndex,
+            rowIndex,
+            page,
+            config,
+        });
+    }
+    return resolve(config.cellSelector, row).nth(columnIndex);
+}
+/**
+ * Cell locator for Playwright `rows.filter({ has })`.
+ *
+ * When `getCellLocator` is set, pass `page.locator(':scope')` as the row so the
+ * strategy's `row.locator(...)` chain stays relative to each candidate row under
+ * `filter({ has })`. Using the rows collection or a document-rooted parent nests
+ * the row selector and matches nothing.
+ *
+ * Without `getCellLocator`, keeps the historical page-scoped `cellSelector.nth(i)`
+ * template that Playwright re-bases into each row.
+ */
+function resolveCellLocatorForFilter(args) {
+    var _a;
+    const { config, resolve, page, root, columnName, columnIndex } = args;
+    if ((_a = config.strategies) === null || _a === void 0 ? void 0 : _a.getCellLocator) {
+        const scopeRow = page.locator(':scope');
+        return config.strategies.getCellLocator({
+            row: scopeRow,
+            root: root !== null && root !== void 0 ? root : scopeRow,
+            columnName,
+            columnIndex,
+            page,
+            config,
+        });
+    }
+    return resolve(config.cellSelector, page).nth(columnIndex);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.20.1-next.720a2e5",
+  "version": "6.20.1-next.a5f5df2",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",