@rickcedwhat/playwright-smart-table 6.25.0-next.c784f2c → 6.25.0-next.d8860d0

package/dist/strategies/columns.d.ts

@@ -2,7 +2,7 @@ import type { Locator } from '@playwright/test';
 import { StrategyContext } from '../types';
 /**
  * Primitive navigation functions that define HOW to move within a table.
- * The orchestration logic (WHEN to move) lives in _navigateToCell.
+ * The orchestration logic (WHEN to move) lives in navigateToCell (src/engine/cellNavigation.ts).
  */
 export interface NavigationPrimitives {
     goUp?: (context: StrategyContext) => Promise<void>;

package/dist/strategies/contentReady.d.ts

@@ -1,5 +1,23 @@
-import type { ContentReadyStrategy } from '../types';
+import type { ContentReadyStrategy, RowReadyPredicate } from '../types';
 export declare const ContentReadyStrategies: {
+    /**
+     * Waits in the browser until `predicate(rowElement, arg)` returns a truthy value, e.g. until
+     * a skeleton placeholder is gone or every cell has rendered. Resolves when `timeout` expires
+     * even if the predicate never passed, like the other content-ready strategies.
+     *
+     * Uses `locator.waitForFunction` (Playwright 1.62+), which re-resolves the row on each retry
+     * and polls without a round-trip per check. Older versions poll via `locator.evaluate`.
+     * `timeout` and `interval` must be positive finite milliseconds. `interval` only controls
+     * the older-version fallback; native polling is controlled by Playwright.
+     *
+     * @example
+     * contentReady: Strategies.ContentReady.until(row => !row.querySelector('.skeleton'))
+     */
+    until: <Arg = undefined>(predicate: RowReadyPredicate<Arg>, options?: {
+        arg?: Arg;
+        timeout?: number;
+        interval?: number;
+    }) => ContentReadyStrategy;
     /**
      * Polls the row's text content until two consecutive reads match.
      */

package/dist/strategies/contentReady.js

@@ -1,7 +1,88 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContentReadyStrategies = void 0;
+function isTimeout(error) {
+    return (error === null || error === void 0 ? void 0 : error.name) === 'TimeoutError';
+}
+/** Playwright < 1.62 has no `locator.waitForFunction`: poll with one `evaluate` per check. */
+async function pollPredicate(row, page, predicate, arg, timeout, interval) {
+    const deadline = Date.now() + timeout;
+    let source = predicate.toString();
+    // Build a serializable callback; the user predicate executes only inside the browser.
+    const wrap = (expression) => new Function(`return async (row, arg) => Boolean(await (${expression})(row, arg))`)();
+    let evaluateBoolean;
+    try {
+        evaluateBoolean = wrap(source);
+    }
+    catch (_a) {
+        // Like Playwright's serializer, normalize method shorthand into a function expression.
+        source = source.startsWith('async ') ? source.replace(/^async\s+/, 'async function ') : `function ${source}`;
+        evaluateBoolean = wrap(source);
+    }
+    let expired = false;
+    let deadlineTimer;
+    const timeoutReached = new Promise(resolve => {
+        deadlineTimer = setTimeout(() => { expired = true; resolve(); }, timeout);
+    });
+    const poll = async () => {
+        while (!expired && Date.now() < deadline) {
+            // Convert truthiness before serialization, including async DOM-element results.
+            if (await row.evaluate(evaluateBoolean, arg, { timeout: Math.max(1, deadline - Date.now()) }))
+                return;
+            if (expired || Date.now() >= deadline)
+                return;
+            await page.waitForTimeout(Math.min(interval, Math.max(0, deadline - Date.now())));
+        }
+    };
+    try {
+        // evaluate's timeout only bounds locator resolution, not an async predicate's promise.
+        await Promise.race([poll(), timeoutReached]);
+    }
+    finally {
+        clearTimeout(deadlineTimer);
+    }
+}
 exports.ContentReadyStrategies = {
+    /**
+     * Waits in the browser until `predicate(rowElement, arg)` returns a truthy value, e.g. until
+     * a skeleton placeholder is gone or every cell has rendered. Resolves when `timeout` expires
+     * even if the predicate never passed, like the other content-ready strategies.
+     *
+     * Uses `locator.waitForFunction` (Playwright 1.62+), which re-resolves the row on each retry
+     * and polls without a round-trip per check. Older versions poll via `locator.evaluate`.
+     * `timeout` and `interval` must be positive finite milliseconds. `interval` only controls
+     * the older-version fallback; native polling is controlled by Playwright.
+     *
+     * @example
+     * contentReady: Strategies.ContentReady.until(row => !row.querySelector('.skeleton'))
+     */
+    until: (predicate, options = {}) => {
+        var _a, _b;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : 500;
+        const interval = (_b = options.interval) !== null && _b !== void 0 ? _b : 50;
+        if (!Number.isFinite(timeout) || timeout <= 0) {
+            throw new Error('ContentReady.until: timeout must be a positive finite number');
+        }
+        if (!Number.isFinite(interval) || interval <= 0) {
+            throw new Error('ContentReady.until: interval must be a positive finite number');
+        }
+        const fn = predicate;
+        const arg = options.arg;
+        return async (row, page) => {
+            try {
+                if (typeof row.waitForFunction === 'function') {
+                    await row.waitForFunction(fn, arg, { timeout });
+                }
+                else {
+                    await pollPredicate(row, page, fn, arg, timeout, interval);
+                }
+            }
+            catch (error) {
+                if (!isTimeout(error))
+                    throw error;
+            }
+        };
+    },
     /**
      * Polls the row's text content until two consecutive reads match.
      */

package/dist/strategies/dedupe.d.ts

@@ -1,8 +1,11 @@
 import { DedupeStrategy } from '../types';
 export declare const DedupeStrategies: {
     /**
-     * Deduplicates rows based on their vertical position (Y coordinate).
-     * Useful for virtualized tables where row DOM elements are reused but content changes.
+     * Groups rows by their viewport Y coordinate, rounded to a pixel bucket.
+     * Only applicable when each screen position represents the same record for the entire scan.
+     * Scrolling or pagination can place different records at the same position and silently drop them.
+     * @deprecated Prefer a stable record key, e.g. `async row => row.getCell('ID').innerText()`.
+     * Do not use for recycled virtualized rows or paginated tables.
      * @param tolerance Pixel tolerance for position comparison (default: 2)
      */
     byTopPosition: (tolerance?: number) => DedupeStrategy;

package/dist/strategies/dedupe.js

@@ -3,8 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DedupeStrategies = void 0;
 exports.DedupeStrategies = {
     /**
-     * Deduplicates rows based on their vertical position (Y coordinate).
-     * Useful for virtualized tables where row DOM elements are reused but content changes.
+     * Groups rows by their viewport Y coordinate, rounded to a pixel bucket.
+     * Only applicable when each screen position represents the same record for the entire scan.
+     * Scrolling or pagination can place different records at the same position and silently drop them.
+     * @deprecated Prefer a stable record key, e.g. `async row => row.getCell('ID').innerText()`.
+     * Do not use for recycled virtualized rows or paginated tables.
      * @param tolerance Pixel tolerance for position comparison (default: 2)
      */
     byTopPosition: (tolerance = 2) => async (row) => {

package/dist/strategies/index.d.ts

@@ -98,6 +98,11 @@ export declare const Strategies: {
         dataAttribute: (options?: import("./viewport").DataAttributeViewportOptions) => import("..").ViewportStrategy;
     };
     ContentReady: {
+        until: <Arg = undefined>(predicate: import("..").RowReadyPredicate<Arg>, options?: {
+            arg?: Arg;
+            timeout?: number;
+            interval?: number;
+        }) => import("..").ContentReadyStrategy;
         textStable: (options?: {
             timeout?: number;
             interval?: number;

package/dist/types.d.ts

@@ -210,9 +210,9 @@ export interface ViewportStrategy {
     scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;
     /**
      * When true, disables the automatic memoization of getVisibleColumnRange and
-     * getVisibleRowRange results. By default the library caches each range value and
-     * invalidates it after the corresponding scroll call, eliminating redundant DOM
-     * evaluate() round-trips between scrolls.
+     * getVisibleRowRange results within a single cell-navigation operation. Geometry
+     * is refreshed for each new read and around scroll calls. Row membership is not
+     * memoized by the library. Caches never persist across scans, resets, or revalidation.
      */
     disableCache?: boolean;
 }
@@ -426,8 +426,15 @@ export interface PaginationPrimitives {
     detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;
 }
 export type PaginationStrategy = PaginationPrimitives;
+/**
+ * Returns a stable record key across the entire scan, including page advances.
+ * Different records must have different keys; viewport coordinates and mounted DOM indices
+ * are not stable identities in recycled or paginated tables.
+ */
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export type ContentReadyStrategy = (row: Locator, page: Page) => Promise<void>;
+/** Predicate for `Strategies.ContentReady.until`. Runs in the browser with the row element, so it must not close over test-side variables; pass values via `arg`. */
+export type RowReadyPredicate<Arg = undefined> = (row: HTMLElement | SVGElement, arg: Arg) => unknown;
 export type FillStrategy = (options: {
     row: SmartRow;
     columnName: string;
@@ -524,6 +531,7 @@ export interface LoadingStrategy {
      * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.
      * Honored by findRows AND by map/forEach/filter, where the wait runs before the dedupe
      * strategy so content-based dedupe keys see the row's final loaded state.
+     * Includes time spent awaiting the loading predicate, even if it never settles.
      * When not set (backward-compatible behavior): findRows skips loading rows immediately;
      * map/forEach/filter process them as-is.
      */
@@ -544,6 +552,7 @@ export interface LoadingStrategy {
     isCellLoading?: (cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<boolean>;
     /**
      * How long (ms) to wait for a loading cell to resolve before applying onCellLoadingTimeout.
+     * Includes predicate evaluation and any initial rendering grace period.
      * When not set and isCellLoading returns true, the cell is read as-is immediately.
      */
     cellLoadingTimeout?: number;
@@ -638,12 +647,18 @@ export interface TableStrategies {
      * 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.
+     * Built-ins: `Strategies.ContentReady.textStable()` (text stops changing),
+     * `mutationSettled()` (no DOM mutations for a quiet period), and `until(predicate)`
+     * (an in-browser condition holds, e.g. no skeleton placeholder).
      *
      * @example
      * strategies: {
      *   contentReady: Strategies.ContentReady.textStable({ timeout: 500 }),
      * }
+     * @example
+     * strategies: {
+     *   contentReady: Strategies.ContentReady.until(row => !row.querySelector('.skeleton')),
+     * }
      */
     contentReady?: ContentReadyStrategy;
     /**
@@ -794,6 +809,11 @@ export type RowIterationOptions = {
      * @default false — uses goNext for one-page-at-a-time advancement
      */
     useBulkPagination?: boolean;
+    /**
+     * Cancels the iteration between pages. When aborted, the call rejects with
+     * `signal.reason` (rows already processed are not returned).
+     */
+    signal?: AbortSignal;
 };
 /**
  * Result of {@link useTable}. Implements `AsyncIterable` — `for await (const { row } of table)`
@@ -876,31 +896,37 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * is not configured. Also throws if the row cannot be reached (no silent wrong-row fallback).
      *
      * @param index 0-based logical/data-model row index
-     * @param options - `maxPages` bounds how far to scroll/paginate (defaults to config.maxPages)
+     * @param options - `maxPages` bounds how far to scroll/paginate (defaults to config.maxPages).
+     * `signal` cancels the page scan; the call rejects with `signal.reason`.
      */
     findRowByIndex: (index: number, options?: {
         maxPages?: number;
+        signal?: AbortSignal;
     }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for a single row across pages using pagination.
      * Auto-initializes the table if not already initialized.
      * @param filters - The filter criteria to match
-     * @param options - Search options including exact match and max pages
+     * @param options - Search options including exact match and max pages. `signal` cancels the page scan; the call rejects with `signal.reason`.
      */
     findRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
+        signal?: AbortSignal;
     }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for all matching rows across pages using pagination.
      * Auto-initializes the table if not already initialized.
+     * Returned rows can be read independently, including with `concurrency: 'synchronized'`.
+     * Use synchronized `map()` for coordinated column scrolling across virtualized rows.
      * @param filters - The filter criteria to match (omit or pass {} for all rows)
-     * @param options - Search options (exact, maxPages). `useBulkPagination` defaults to `false`: pages advance one at a time via `goNext` so no intermediate page is skipped. Set it to `true` to opt into `goNextBulk` (faster, but skips the rows on jumped-over pages).
+     * @param options - Search options (exact, maxPages). `useBulkPagination` defaults to `false`: pages advance one at a time via `goNext` so no intermediate page is skipped. Set it to `true` to opt into `goNextBulk` (faster, but skips the rows on jumped-over pages). `signal` cancels the page scan; the call rejects with `signal.reason`.
      */
     findRows: (filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
         useBulkPagination?: boolean;
+        signal?: AbortSignal;
     }) => Promise<SmartRowArray<T>>;
     /**
      * Resolves the named column and scrolls it into view.
@@ -911,11 +937,13 @@ export interface TableResult<T = any> extends AsyncIterable<{
     /**
      * Counts the number of rows, optionally filtered.
      * Without arguments, counts all rows. With filters, counts only matching rows.
-     * Paginates when pagination is configured.
+     * Paginates when pagination is configured. `signal` cancels the page scan; the call
+     * rejects with `signal.reason` (the table is still reset to page 1).
      */
     countRows: (filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
+        signal?: AbortSignal;
     }) => Promise<number>;
     /**
      * Iterates over rows and extracts the value of a single column.