@rickcedwhat/playwright-smart-table 6.24.0 → 6.25.0-next.1e71a54

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,6 +1,23 @@
-import type { ContentReadyStrategy } from '../types';
-export type { ContentReadyStrategy };
+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/index.d.ts

@@ -3,7 +3,6 @@ export * from './sorting';
 export * from './columns';
 export * from './headers';
 export * from './fill';
-export type { ColumnResolutionStrategy } from './resolution';
 export * from './dedupe';
 export * from './loading';
 export * from './stabilization';
@@ -99,13 +98,18 @@ 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;
-        }) => import("./contentReady").ContentReadyStrategy;
+        }) => import("..").ContentReadyStrategy;
         mutationSettled: (options?: {
             timeout?: number;
             quietPeriod?: number;
-        }) => import("./contentReady").ContentReadyStrategy;
+        }) => import("..").ContentReadyStrategy;
     };
 };

package/dist/strategies/resolution.d.ts

@@ -1,4 +1,5 @@
 import { StrategyContext } from '../types';
+/** @deprecated Not used by the library. Will be removed in v7. */
 export interface ColumnResolutionStrategy {
     /**
      * Resolves a column name (string or Regex) to a column index.
@@ -17,6 +18,3 @@ export interface ColumnResolutionStrategy {
         headerMap: Map<string, number>;
     }): string;
 }
-export declare const ResolutionStrategies: {
-    default: ColumnResolutionStrategy;
-};

package/dist/strategies/resolution.js

@@ -1,30 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResolutionStrategies = void 0;
-exports.ResolutionStrategies = {
-    default: {
-        resolveIndex: ({ query, headerMap }) => {
-            // 1. Exact / String Match
-            if (typeof query === 'string') {
-                if (headerMap.has(query))
-                    return headerMap.get(query);
-            }
-            // 2. Regex Match
-            if (query instanceof RegExp) {
-                for (const [colName, idx] of headerMap.entries()) {
-                    if (query.test(colName))
-                        return idx;
-                }
-                return undefined;
-            }
-            // 3. (Optional) Fuzzy String Match fallback could go here
-            // But for strict default strategy, we might want to keep it simple first
-            // The original code didn't do fuzzy *resolution* logic inside the get(), it just did strict get().
-            // The fuzzy logic was only for *suggestions* on error.
-            return undefined;
-        },
-        resolveName: ({ query }) => {
-            return query.toString();
-        }
-    }
-};

package/dist/types.d.ts

@@ -428,6 +428,8 @@ 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>;
+/** 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 +526,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 +547,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 +642,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;
     /**
@@ -760,6 +770,14 @@ export type RowIterationContext<T = any> = {
     index: number;
     /** 0-based page index — which page this row was collected from. */
     pageIndex: number;
+    /**
+     * Ends the iteration. No further pages are loaded, and the result of `map` / `filter`
+     * includes this row and nothing after it. If several rows call `stop()`, the earliest one wins.
+     *
+     * In `'sequential'` mode (the default) no callback after this row runs. In `'parallel'` and
+     * `'synchronized'` mode the rest of the current page is already in flight, so later rows'
+     * callbacks may still run (and their side effects happen) even though their results are dropped.
+     */
     stop: () => void;
 };
 /** Concurrency modes for row iteration. */
@@ -786,6 +804,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)`
@@ -868,31 +891,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.
@@ -903,11 +932,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.
@@ -935,7 +966,8 @@ export interface TableResult<T = any> extends AsyncIterable<{
     /**
      * Iterates every row across all pages, calling the callback for side effects.
      * Execution is sequential by default (safe for interactions like clicking/filling).
-     * Call `stop()` in the callback to end iteration early.
+     * Call `stop()` in the callback to end iteration early. In sequential mode no later row runs;
+     * in parallel mode the rest of the current page may still run (see `RowIterationContext.stop`).
      *
      * @param callback - Function receiving { row, rowIndex, stop }
      * @param options - maxPages, concurrency, dedupe, useBulkPagination
@@ -952,7 +984,8 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Defaults to `concurrency: 'sequential'` (safe for clicks/fills). Pass
      * `concurrency: 'parallel'` for read-only extraction, or `'synchronized'` when
      * navigation must stay lock-step on virtualized grids.
-     * Call `stop()` to halt after the current page finishes.
+     * Call `stop()` to end early: the result includes the row that called it and nothing after it
+     * (in parallel mode, later rows on the same page may still run; see `RowIterationContext.stop`).
      *
      * @param callback - Function receiving { row, rowIndex, stop }
      * @param options - maxPages, concurrency, dedupe, useBulkPagination