@rickcedwhat/playwright-smart-table 6.20.1 → 6.21.0-next.3ab7a18

package/dist/typeContext.js

@@ -284,6 +284,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>;
@@ -309,6 +312,12 @@ export type SmartRow<T = any> = Locator & {
 
   /**
    * 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
    */
@@ -440,6 +449,8 @@ 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: {
@@ -509,6 +520,7 @@ export interface ColumnOverride<TValue = any> {
 }
 
 export type { HeaderStrategy } from './strategies/headers';
+export type { NavigationPrimitives, CellNavigationStrategy } from './strategies/columns';
 
 /**
  * Strategy to resolve column names (string or regex) to their index.
@@ -583,9 +595,16 @@ export interface LoadingStrategy {
     | '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 */
+  /**
+   * Max ms to wait while \`isTableLoading\` returns true (countRows, findRow(s),
+   * page-ready gates, and sort when \`sortStabilizationTimeout\` is unset).
+   * @default 10000
+   */
+  loadingTimeout?: number;
+
+  /** Max ms to wait for sort stabilization when isTableLoading is set. Overrides \`loadingTimeout\` for sort only. @default 10000 */
   sortStabilizationTimeout?: number;
-  /** Polling interval (ms) while waiting for sort stabilization. @default 100 */
+  /** Polling interval (ms) while waiting for sort / table-ready stabilization. @default 100 (sort) / 200 (table-ready) */
   sortStabilizationPollInterval?: number;
   /** Fallback delay (ms) after sort when no isTableLoading is configured. @default 200 */
   sortStabilizationFallbackDelay?: number;
@@ -654,6 +673,24 @@ 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).
@@ -675,11 +712,17 @@ export interface TableConfig<T = any> {
   rowSelector?: string;
   /** Selector for the cells within a row */
   cellSelector?: string | ((row: Locator) => Locator);
-  /** Number of pages to scan for verification */
+  /**
+   * Number of pages to scan for verification / iteration.
+   * Defaults to \`1\` — set explicitly (e.g. \`maxPages: 5\`) when using a pagination
+   * strategy, or you will never leave page 1. Init logs a warning when pagination
+   * is configured and this is still \`1\`.
+   */
   maxPages?: number;
   /**
    * Default concurrency strategy for iteration methods.
    * Can be overridden by the options passed to forEach, map, or filter.
+   * Defaults to sequential when unset (safer for UI interactions).
    */
   concurrency?: RowIterationMode;
   /** Hook to rename columns dynamically */
@@ -715,6 +758,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;
@@ -786,10 +832,17 @@ 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; index: number; pageIndex: number }> {
   /**
-   * Represents the current page index of the table's DOM.
-   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.
+   * Current DOM page index (0-based). Automatically maintained during pagination
+   * and \`bringIntoView\`. Treat as **read-only** — assigning manually can desync
+   * the path planner. Manual writes log a warning; prefer \`reset()\` / library
+   * navigation. Writable access may become read-only in v7.
    */
   currentPageIndex: number;
 
@@ -821,6 +874,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * @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>,
@@ -890,7 +946,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   ) => 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>;
 
@@ -910,6 +968,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   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
@@ -949,28 +1008,29 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
 
   /**
    * Transforms every row across all pages into a value. Returns a flat array.
-   * Execution is parallel within each page by default (safe for reads).
+   * 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.
    *
-   * > **⚠️ UI Interactions:** \`map\` defaults to \`concurrency: 'parallel'\`. If your callback opens popovers,
-   * > fills inputs, or otherwise mutates UI state, pass \`concurrency: 'sequential'\` (or \`'synchronized'\`
-   * > when navigation must stay lock-step) to avoid overlapping interactions.
-   *
    * @param callback - Function receiving { row, rowIndex, stop }
    * @param options - maxPages, concurrency, dedupe, useBulkPagination
    *
    * @example
-   * // Data extraction — parallel is safe
-   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
-   *
-   * @example
-   * // UI interactions — use sequential (or synchronized) concurrency
+   * // Default sequential — safe for UI interactions
    * const assignees = await table.map(async ({ row }) => {
    *   await row.getCell('Assignee').locator('button').click();
    *   const name = await page.locator('.popover .name').innerText();
    *   await page.keyboard.press('Escape');
    *   return name;
-   * }, { concurrency: 'sequential' });
+   * });
+   *
+   * @example
+   * // Read-only extraction — opt into parallel
+   * const emails = await table.map(
+   *   ({ row }) => row.getCell('Email').innerText(),
+   *   { concurrency: 'parallel' }
+   * );
    */
   map<R>(
     callback: (ctx: RowIterationContext<T>) => R | Promise<R>,

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.
  */
@@ -530,9 +541,15 @@ 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 */
+    /**
+     * Max ms to wait while `isTableLoading` returns true (countRows, findRow(s),
+     * page-ready gates, and sort when `sortStabilizationTimeout` is unset).
+     * @default 10000
+     */
+    loadingTimeout?: number;
+    /** Max ms to wait for sort stabilization when isTableLoading is set. Overrides `loadingTimeout` for sort only. @default 10000 */
     sortStabilizationTimeout?: number;
-    /** Polling interval (ms) while waiting for sort stabilization. @default 100 */
+    /** Polling interval (ms) while waiting for sort / table-ready stabilization. @default 100 (sort) / 200 (table-ready) */
     sortStabilizationPollInterval?: number;
     /** Fallback delay (ms) after sort when no isTableLoading is configured. @default 200 */
     sortStabilizationFallbackDelay?: number;
@@ -597,6 +614,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).
@@ -616,11 +650,17 @@ export interface TableConfig<T = any> {
     rowSelector?: string;
     /** Selector for the cells within a row */
     cellSelector?: string | ((row: Locator) => Locator);
-    /** Number of pages to scan for verification */
+    /**
+     * Number of pages to scan for verification / iteration.
+     * Defaults to `1` — set explicitly (e.g. `maxPages: 5`) when using a pagination
+     * strategy, or you will never leave page 1. Init logs a warning when pagination
+     * is configured and this is still `1`.
+     */
     maxPages?: number;
     /**
      * Default concurrency strategy for iteration methods.
      * Can be overridden by the options passed to forEach, map, or filter.
+     * Defaults to sequential when unset (safer for UI interactions).
      */
     concurrency?: RowIterationMode;
     /** Hook to rename columns dynamically */
@@ -657,6 +697,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 +768,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;
@@ -732,8 +780,10 @@ export interface TableResult<T = any> extends AsyncIterable<{
     pageIndex: number;
 }> {
     /**
-     * Represents the current page index of the table's DOM.
-     * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.
+     * Current DOM page index (0-based). Automatically maintained during pagination
+     * and `bringIntoView`. Treat as **read-only** — assigning manually can desync
+     * the path planner. Manual writes log a warning; prefer `reset()` / library
+     * navigation. Writable access may become read-only in v7.
      */
     currentPageIndex: number;
     /**
@@ -762,6 +812,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 +876,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 +898,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
@@ -874,28 +930,29 @@ export interface TableResult<T = any> extends AsyncIterable<{
     forEach(callback: (ctx: RowIterationContext<T>) => void | Promise<void>, options?: RowIterationOptions): Promise<void>;
     /**
      * Transforms every row across all pages into a value. Returns a flat array.
-     * Execution is parallel within each page by default (safe for reads).
+     * 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.
      *
-     * > **⚠️ UI Interactions:** `map` defaults to `concurrency: 'parallel'`. If your callback opens popovers,
-     * > fills inputs, or otherwise mutates UI state, pass `concurrency: 'sequential'` (or `'synchronized'`
-     * > when navigation must stay lock-step) to avoid overlapping interactions.
-     *
      * @param callback - Function receiving { row, rowIndex, stop }
      * @param options - maxPages, concurrency, dedupe, useBulkPagination
      *
      * @example
-     * // Data extraction — parallel is safe
-     * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
-     *
-     * @example
-     * // UI interactions — use sequential (or synchronized) concurrency
+     * // Default sequential — safe for UI interactions
      * const assignees = await table.map(async ({ row }) => {
      *   await row.getCell('Assignee').locator('button').click();
      *   const name = await page.locator('.popover .name').innerText();
      *   await page.keyboard.press('Escape');
      *   return name;
-     * }, { concurrency: 'sequential' });
+     * });
+     *
+     * @example
+     * // Read-only extraction — opt into parallel
+     * const emails = await table.map(
+     *   ({ row }) => row.getCell('Email').innerText(),
+     *   { concurrency: 'parallel' }
+     * );
      */
     map<R>(callback: (ctx: RowIterationContext<T>) => R | Promise<R>, options?: RowIterationOptions): Promise<R[]>;
     /**