@rickcedwhat/playwright-smart-table 6.17.1 → 6.19.0

package/dist/typeContext.js

@@ -167,6 +167,16 @@ export interface ViewportStrategy {
    */
   getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;
 
+  /**
+   * Returns the DOM positions (0-based, document order — indices into the resolved
+   * \`rowSelector\` set) of rows currently within the scroll container's visible bounds.
+   * Unlike \`getVisibleRowRange\` (a logical min/max), this identifies the exact rows, so
+   * \`map\`/\`forEach\`/\`filter\` can skip overscan rows during collection (see #353 / #357).
+   * Geometry-based and inclusive (any overlap counts as visible). When the container can't
+   * be measured, return all positions so no rows are filtered.
+   */
+  getVisibleRowIndices?: (context: TableContext) => Promise<number[]>;
+
   /**
    * Returns the 0-based index range of columns currently rendered in the DOM.
    * Used to detect when a target column is not yet mounted before reading.
@@ -254,8 +264,14 @@ export type SmartRow<T = any> = Locator & {
    * 
    * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
    * // { Name: 'John', Email: 'john@example.com' }
+   *
+   * // Atomic: snapshot all cell values in a single evaluate — zero inter-column stagger.
+   * // Requires cellSelector to be a CSS string (not a function).
+   * // Column overrides ARE supported (run against a frozen off-screen reconstruction).
+   * // Uses textContent (not layout-dependent innerText) for non-override columns.
+   * const coherent = await row.toJSON({ atomic: true });
    */
-  toJSON(options?: { columns?: string[] }): Promise<T>;
+  toJSON(options?: { columns?: string[]; atomic?: boolean }): Promise<T>;
 
   /**
    * Scrolls/paginates to bring this row into view.
@@ -424,12 +440,43 @@ export type FillStrategy = (options: {
   fillOptions?: FillOptions;
 }) => Promise<void>;
 
+/** Context passed as the second argument to {@link ColumnOverride.read}. */
+export interface ColumnOverrideReadContext {
+  /**
+   * The parent row. Use for multi-cell or row-derived values — e.g. a synthetic column
+   * that reads an \`a[href]\` or a \`data-*\` attribute from the row rather than a cell:
+   * \`read: (_cell, { row }) => row.evaluate(el => el.querySelector('a')?.href)\`.
+   */
+  row: SmartRow;
+  /** The column being read. */
+  columnName: string;
+  /** The column's 0-based index in the resolved header map. */
+  columnIndex: number;
+  /**
+   * Get a Locator for another cell in the same row by column name.
+   * Returns raw cell Locators, not override-processed values.
+   *
+   * In atomic mode, the Locator points at the frozen reconstructed cell — coherent with
+   * every other cell from the same snapshot. In non-atomic mode, it points at the live cell.
+   *
+   * @example
+   * read: async (_cell, { getCell }) => {
+   *   const name = (await getCell('Name').innerText()).trim();
+   *   const href = await getCell('Name').locator('a').getAttribute('href') || '';
+   *   return \`\${name} | \${href}\`;
+   * }
+   */
+  getCell: (columnName: string) => Locator;
+}
+
 export interface ColumnOverride<TValue = any> {
-  /** 
+  /**
    * How to extract the value from the cell.
-   * \`context\` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.
+   * The second \`context\` argument provides the parent \`row\` (for multi-cell or row-derived
+   * values), plus \`columnName\` and \`columnIndex\`. Backwards-compatible: existing
+   * single-argument \`read(cell)\` implementations keep working.
    */
-  read?: (cell: Locator) => Promise<TValue> | TValue;
+  read?: (cell: Locator, context: ColumnOverrideReadContext) => Promise<TValue> | TValue;
 
   /** 
    * How to fill the cell with a new value. (Replaces smartFill default logic)
@@ -475,7 +522,10 @@ export interface LoadingStrategy {
 
   /**
    * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.
-   * When not set, loading rows are immediately skipped (backward-compatible behavior).
+   * 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.
+   * When not set (backward-compatible behavior): findRows skips loading rows immediately;
+   * map/forEach/filter process them as-is.
    */
   rowLoadingTimeout?: number;
 
@@ -617,6 +667,13 @@ export interface TableConfig<T = any> {
    * Overrides both default extraction (toJSON) and filling (smartFill) logic.
    */
   columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
+
+  /**
+   * Locator for an empty-state element that replaces the table when there are no results.
+   * If header resolution fails during init() and this locator is visible, init() succeeds
+   * and isEmpty() returns true. All row operations still throw normally.
+   */
+  emptyState?: Locator;
 }
 
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
@@ -646,9 +703,17 @@ export interface FillOptions {
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
   row: SmartRow<T>;
-  /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. @deprecated Use \`index\` instead. \`rowIndex\` will be removed in v7.0.0. */
+  /**
+   * The row's logical/data-model index. When a \`resolveRowIndex\` strategy is configured
+   * (e.g. MUI DataGrid's \`data-rowindex\`) this is the grid's true row index; otherwise it
+   * equals \`index\`. Use this for \`row.bringIntoView()\` and position math on virtualized
+   * tables — it is stable across scrolling/dedupe, unlike the visit-order \`index\`.
+   */
   rowIndex: number;
-  /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
+  /**
+   * 0-based enumeration counter — the order this row was visited (contiguous within the run).
+   * Not a DOM position or grid identity. Use \`rowIndex\` for the row's data-model index.
+   */
   index: number;
   /** 0-based page index — which page this row was collected from. */
   pageIndex: number;
@@ -701,14 +766,22 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    */
   isInitialized(): boolean;
 
+  /**
+   * SYNC: Returns true if init() resolved via the emptyState path — the table's
+   * empty-state locator was visible when header resolution failed.
+   * Row operations still throw normally; use this to branch before calling them.
+   */
+  isEmpty(): boolean;
+
   getHeaders: () => Promise<string[]>;
   getHeaderCell: (columnName: string) => Promise<Locator>;
 
   /**
    * Finds a row by filters on the current page only. Returns immediately (sync).
    * Throws error if table is not initialized.
-   * @note The returned SmartRow may have \`rowIndex\` as 0 when the match is not the first row.
-   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).
+   * @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\`.
    */
   getRow: (
     filters: Record<string, FilterValue>,
@@ -716,14 +789,45 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   ) => SmartRow<T>;
 
   /**
-   * Gets a row by 0-based index on the current page.
-   * Throws error if table is not initialized.
-   * @param index 0-based row index
+   * Gets a row by its 0-based position in the currently-rendered DOM (sync, no scroll).
+   * Throws if the table is not initialized.
+   *
+   * For button-paginated tables this is the i-th row on the current page. For virtualized
+   * tables the render window shifts as you scroll, so \`getRowByIndex(i)\` returns whatever
+   * row currently sits at DOM position \`i\` — NOT the logical/absolute row \`i\` in the dataset
+   * once the list has scrolled. For the row with a specific logical/data-model index on a
+   * virtualized table, use the async \`findRowByIndex(i)\` instead (it scrolls to the row);
+   * to iterate by logical identity, use \`map\` / \`findRows\` (with a \`dedupe\` strategy).
+   *
+   * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when
+   * it is used, rather than throwing here.
+   *
+   * @param index 0-based position within the current render window
    */
   getRowByIndex: (
     index: number
   ) => SmartRow<T>;
 
+  /**
+   * ASYNC: Returns the row with a specific logical/data-model index, scrolling/paginating to
+   * reach it. Unlike the sync \`getRowByIndex\` (render-window position), this resolves the true
+   * data-model row \`index\` on virtualized tables.
+   *
+   * Reaches the row via, in order: a currently-mounted match, the viewport's random-access
+   * \`scrollToRow\` fast path, then advancing pages (on infinite-scroll tables a "page" is a
+   * scroll step) up to \`maxPages\`.
+   *
+   * Requires a \`strategies.resolveRowIndex\` to identify rows by logical index — throws if one
+   * 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)
+   */
+  findRowByIndex: (
+    index: number,
+    options?: { maxPages?: number }
+  ) => Promise<SmartRow<T>>;
+
   /**
    * ASYNC: Searches for a single row across pages using pagination.
    * Auto-initializes the table if not already initialized.
@@ -739,7 +843,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * ASYNC: Searches for all matching rows across pages using pagination.
    * Auto-initializes the table if not already initialized.
    * @param filters - The filter criteria to match (omit or pass {} for all rows)
-   * @param options - Search options including exact match and max 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).
    */
   findRows: (
     filters?: Record<string, FilterValue>,

package/dist/types.d.ts

@@ -157,6 +157,15 @@ export interface ViewportStrategy {
         first: number;
         last: number;
     }>;
+    /**
+     * Returns the DOM positions (0-based, document order — indices into the resolved
+     * `rowSelector` set) of rows currently within the scroll container's visible bounds.
+     * Unlike `getVisibleRowRange` (a logical min/max), this identifies the exact rows, so
+     * `map`/`forEach`/`filter` can skip overscan rows during collection (see #353 / #357).
+     * Geometry-based and inclusive (any overlap counts as visible). When the container can't
+     * be measured, return all positions so no rows are filtered.
+     */
+    getVisibleRowIndices?: (context: TableContext) => Promise<number[]>;
     /**
      * Returns the 0-based index range of columns currently rendered in the DOM.
      * Used to detect when a target column is not yet mounted before reading.
@@ -236,9 +245,16 @@ export type SmartRow<T = any> = Locator & {
      *
      * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
      * // { Name: 'John', Email: 'john@example.com' }
+     *
+     * // Atomic: snapshot all cell values in a single evaluate — zero inter-column stagger.
+     * // Requires cellSelector to be a CSS string (not a function).
+     * // Column overrides ARE supported (run against a frozen off-screen reconstruction).
+     * // Uses textContent (not layout-dependent innerText) for non-override columns.
+     * const coherent = await row.toJSON({ atomic: true });
      */
     toJSON(options?: {
         columns?: string[];
+        atomic?: boolean;
     }): Promise<T>;
     /**
      * Scrolls/paginates to bring this row into view.
@@ -383,12 +399,42 @@ export type FillStrategy = (options: {
     table: TableResult;
     fillOptions?: FillOptions;
 }) => Promise<void>;
+/** Context passed as the second argument to {@link ColumnOverride.read}. */
+export interface ColumnOverrideReadContext {
+    /**
+     * The parent row. Use for multi-cell or row-derived values — e.g. a synthetic column
+     * that reads an `a[href]` or a `data-*` attribute from the row rather than a cell:
+     * `read: (_cell, { row }) => row.evaluate(el => el.querySelector('a')?.href)`.
+     */
+    row: SmartRow;
+    /** The column being read. */
+    columnName: string;
+    /** The column's 0-based index in the resolved header map. */
+    columnIndex: number;
+    /**
+     * Get a Locator for another cell in the same row by column name.
+     * Returns raw cell Locators, not override-processed values.
+     *
+     * In atomic mode, the Locator points at the frozen reconstructed cell — coherent with
+     * every other cell from the same snapshot. In non-atomic mode, it points at the live cell.
+     *
+     * @example
+     * read: async (_cell, { getCell }) => {
+     *   const name = (await getCell('Name').innerText()).trim();
+     *   const href = await getCell('Name').locator('a').getAttribute('href') || '';
+     *   return `${name} | ${href}`;
+     * }
+     */
+    getCell: (columnName: string) => Locator;
+}
 export interface ColumnOverride<TValue = any> {
     /**
      * How to extract the value from the cell.
-     * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.
+     * The second `context` argument provides the parent `row` (for multi-cell or row-derived
+     * values), plus `columnName` and `columnIndex`. Backwards-compatible: existing
+     * single-argument `read(cell)` implementations keep working.
      */
-    read?: (cell: Locator) => Promise<TValue> | TValue;
+    read?: (cell: Locator, context: ColumnOverrideReadContext) => Promise<TValue> | TValue;
     /**
      * How to fill the cell with a new value. (Replaces smartFill default logic)
      * Provides the current value (via `read`) if a `write` wants to check state first.
@@ -432,7 +478,10 @@ export interface LoadingStrategy {
     isHeaderLoading?: (context: TableContext) => Promise<boolean>;
     /**
      * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.
-     * When not set, loading rows are immediately skipped (backward-compatible behavior).
+     * 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.
+     * When not set (backward-compatible behavior): findRows skips loading rows immediately;
+     * map/forEach/filter process them as-is.
      */
     rowLoadingTimeout?: number;
     /**
@@ -564,6 +613,12 @@ export interface TableConfig<T = any> {
      * Overrides both default extraction (toJSON) and filling (smartFill) logic.
      */
     columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
+    /**
+     * Locator for an empty-state element that replaces the table when there are no results.
+     * If header resolution fails during init() and this locator is visible, init() succeeds
+     * and isEmpty() returns true. All row operations still throw normally.
+     */
+    emptyState?: Locator;
 }
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
     headerSelector: string | ((root: Locator) => Locator);
@@ -592,9 +647,17 @@ export interface FillOptions {
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
     row: SmartRow<T>;
-    /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. @deprecated Use `index` instead. `rowIndex` will be removed in v7.0.0. */
+    /**
+     * The row's logical/data-model index. When a `resolveRowIndex` strategy is configured
+     * (e.g. MUI DataGrid's `data-rowindex`) this is the grid's true row index; otherwise it
+     * equals `index`. Use this for `row.bringIntoView()` and position math on virtualized
+     * tables — it is stable across scrolling/dedupe, unlike the visit-order `index`.
+     */
     rowIndex: number;
-    /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
+    /**
+     * 0-based enumeration counter — the order this row was visited (contiguous within the run).
+     * Not a DOM position or grid identity. Use `rowIndex` for the row's data-model index.
+     */
     index: number;
     /** 0-based page index — which page this row was collected from. */
     pageIndex: number;
@@ -648,23 +711,59 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * @returns true if init() has been called and completed, false otherwise
      */
     isInitialized(): boolean;
+    /**
+     * SYNC: Returns true if init() resolved via the emptyState path — the table's
+     * empty-state locator was visible when header resolution failed.
+     * Row operations still throw normally; use this to branch before calling them.
+     */
+    isEmpty(): boolean;
     getHeaders: () => Promise<string[]>;
     getHeaderCell: (columnName: string) => Promise<Locator>;
     /**
      * Finds a row by filters on the current page only. Returns immediately (sync).
      * Throws error if table is not initialized.
-     * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.
-     * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).
+     * @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`.
      */
     getRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
     }) => SmartRow<T>;
     /**
-     * Gets a row by 0-based index on the current page.
-     * Throws error if table is not initialized.
-     * @param index 0-based row index
+     * Gets a row by its 0-based position in the currently-rendered DOM (sync, no scroll).
+     * Throws if the table is not initialized.
+     *
+     * For button-paginated tables this is the i-th row on the current page. For virtualized
+     * tables the render window shifts as you scroll, so `getRowByIndex(i)` returns whatever
+     * row currently sits at DOM position `i` — NOT the logical/absolute row `i` in the dataset
+     * once the list has scrolled. For the row with a specific logical/data-model index on a
+     * virtualized table, use the async `findRowByIndex(i)` instead (it scrolls to the row);
+     * to iterate by logical identity, use `map` / `findRows` (with a `dedupe` strategy).
+     *
+     * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when
+     * it is used, rather than throwing here.
+     *
+     * @param index 0-based position within the current render window
      */
     getRowByIndex: (index: number) => SmartRow<T>;
+    /**
+     * ASYNC: Returns the row with a specific logical/data-model index, scrolling/paginating to
+     * reach it. Unlike the sync `getRowByIndex` (render-window position), this resolves the true
+     * data-model row `index` on virtualized tables.
+     *
+     * Reaches the row via, in order: a currently-mounted match, the viewport's random-access
+     * `scrollToRow` fast path, then advancing pages (on infinite-scroll tables a "page" is a
+     * scroll step) up to `maxPages`.
+     *
+     * Requires a `strategies.resolveRowIndex` to identify rows by logical index — throws if one
+     * 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)
+     */
+    findRowByIndex: (index: number, options?: {
+        maxPages?: number;
+    }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for a single row across pages using pagination.
      * Auto-initializes the table if not already initialized.
@@ -679,7 +778,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * ASYNC: Searches for all matching rows across pages using pagination.
      * Auto-initializes the table if not already initialized.
      * @param filters - The filter criteria to match (omit or pass {} for all rows)
-     * @param options - Search options including exact match and max 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).
      */
     findRows: (filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;