@rickcedwhat/playwright-smart-table 6.9.0 → 6.10.1

package/dist/typeContext.js

@@ -14,7 +14,7 @@ exports.TYPE_CONTEXT = `
  * rowSelector: 'tbody tr'
  * 
  * // Function selector
- * rowSelector: (root) => root.locator('[role="row"]')
+ * headerSelector: (root) => root.locator('[role="columnheader"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
 
@@ -37,10 +37,13 @@ export type FilterValue = string | RegExp | number | ((cell: Locator) => Locator
  */
 export type GetCellLocatorFn = (args: {
   row: Locator;
+  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */
+  root: Locator;
   columnName: string;
   columnIndex: number;
   rowIndex?: number;
   page: Page;
+  config: FinalTableConfig<any>;
 }) => Locator;
 
 /**
@@ -80,6 +83,103 @@ export type GetActiveCellFn = (args: TableContext) => Promise<{
   locator: Locator;
 } | null>;
 
+/**
+ * Viewport oracle strategies for virtualized tables.
+ *
+ * These tell the library *what is currently in the DOM* rather than *how to move*.
+ * When present, the cell-reading engine uses them to jump directly to a target
+ * row/column instead of stepping blindly with navigation primitives.
+ *
+ * This is the primary fix for the 2D scroll hazard: scrolling right to bring a
+ * column into view can knock rows out of the vertical viewport (and vice versa).
+ * With \`getVisibleRowRange\` the engine detects this and calls \`scrollToRow\` to
+ * restore the row before reading — eliminating the hazard without polling loops.
+ *
+ * All members are optional. Supply whichever the underlying grid exposes:
+ * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.
+ * - Scroll primitives alone enable direct jumps without range awareness.
+ * - Both together give the most reliable, fastest path.
+ *
+ * @example
+ * // MUI DataGrid via apiRef
+ * strategies: {
+ *   viewport: {
+ *     getVisibleRowRange: async ({ root }) =>
+ *       root.evaluate(el => {
+ *         const api = (el as any).__muiDataGrid__;
+ *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };
+ *       }),
+ *     scrollToRow: async ({ root }, rowIndex) =>
+ *       root.evaluate((el, idx) =>
+ *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),
+ *     scrollToColumn: async ({ root }, colIndex) =>
+ *       root.evaluate((el, idx) =>
+ *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),
+ *   }
+ * }
+ *
+ * @example
+ * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)
+ * strategies: {
+ *   viewport: {
+ *     getVisibleRowRange: async ({ root }) =>
+ *       root.evaluate(el => {
+ *         const rows = [...el.querySelectorAll('[role="row"][aria-rowindex]')];
+ *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);
+ *         return { first: Math.min(...idxs), last: Math.max(...idxs) };
+ *       }),
+ *   }
+ * }
+ */
+export interface ViewportStrategy {
+  /**
+   * Returns the 0-based index range of rows currently rendered in the DOM.
+   * Used to detect when a target row has been scrolled out of view and needs recovery.
+   */
+  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: 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.
+   */
+  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;
+
+  /**
+   * Scrolls or jumps directly to make a row visible by 0-based index.
+   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.
+   */
+  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;
+
+  /**
+   * Scrolls or jumps directly to make a column visible by 0-based index.
+   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.
+   */
+  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.
+   */
+  disableCache?: boolean;
+}
+
+
+/**
+ * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.
+ * 
+ * Extends all standard Locator methods (click, isVisible, etc.).
+ */
+export type SmartCell = Locator & {
+  /**
+   * Scrolls/paginates to bring this specific cell into view using the configured strategies.
+   * Useful when the grid is horizontally virtualized and the column must be scrolled
+   * into view before it can be interacted with or read.
+   */
+  bringIntoView(): Promise<void>;
+};
+
 
 /**
  * SmartRow - A Playwright Locator with table-aware methods.
@@ -106,12 +206,13 @@ export type SmartRow<T = any> = Locator & {
   /**
    * Get a cell locator by column name.
    * @param column - Column name (case-sensitive)
-   * @returns Locator for the cell
+   * @returns SmartCell (Locator + bringIntoView)
    * @example
    * const emailCell = row.getCell('Email');
+   * await emailCell.bringIntoView();
    * await expect(emailCell).toHaveText('john@example.com');
    */
-  getCell(column: string): Locator;
+  getCell(column: string): SmartCell;
 
   /**
    * Extract all cell data as a key-value object.
@@ -129,8 +230,9 @@ export type SmartRow<T = any> = Locator & {
 
   /**
    * Scrolls/paginates to bring this row into view.
-   * Only works if rowIndex is known (e.g., from getRowByIndex).
-   * @throws Error if rowIndex is unknown
+   * Works when row position metadata is known (e.g., from getRowByIndex, findRow,
+   * findRows, filter, or async iteration).
+   * @throws Error if row position metadata is unknown
    */
   bringIntoView(): Promise<void>;
 
@@ -240,6 +342,15 @@ export interface PaginationPrimitives {
   /** Jump to first page / scroll to top */
   goToFirst?: (context: TableContext) => Promise<boolean>;
 
+  /** Jump to last page / scroll to bottom */
+  goToLast?: (context: TableContext) => Promise<boolean>;
+
+  /**
+   * Fetch the total number of pages currently available.
+   * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).
+   */
+  getTotalPages?: (context: TableContext) => Promise<number | null>;
+
   /**
    * Jump to specific page index (0-indexed).
    * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6–14).
@@ -252,6 +363,18 @@ export interface PaginationPrimitives {
 
   /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
   previousBulkPages?: number;
+
+  /**
+   * Called once during init() to sync the library's page counter with the actual DOM state.
+   * Use when a table may open on a page other than the first (e.g. a deep-linked URL that
+   * lands on page 5). Returns a 0-indexed page number.
+   * @example
+   * detectCurrentPage: async (root) => {
+   *   const text = await root.locator('[aria-current="page"]').textContent();
+   *   return parseInt(text ?? '1') - 1;
+   * }
+   */
+  detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;
 }
 
 export type PaginationStrategy = PaginationPrimitives;
@@ -358,6 +481,18 @@ export interface TableStrategies {
    * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.
    */
   loading?: LoadingStrategy;
+
+  /**
+   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
+   * Braintrust-style grids where both rows and columns are virtualized simultaneously).
+   *
+   * When present, the cell-reading engine uses these to jump directly to the target
+   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can
+   * knock rows out of the vertical viewport, and vice versa).
+   *
+   * Completely optional and additive — existing \`navigation\` primitives remain the fallback.
+   */
+  viewport?: ViewportStrategy;
 }
 
 
@@ -520,6 +655,26 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    */
   scrollToColumn: (columnName: string) => Promise<void>;
 
+  /**
+   * Counts the number of rows currently on the page.
+   * Does not paginate.
+   */
+  countRows: () => Promise<number>;
+
+  /**
+   * Iterates over rows and extracts the value of a single column.
+   * More efficient than map + toJSON for single-column extraction.
+   * @param columnName - The name of the column to extract
+   * @param options - Iteration options
+   */
+  mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;
+
+  /**
+   * 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
+   */
+  getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;
 
 
   /**

package/dist/types.d.ts

@@ -7,7 +7,7 @@ import type { SmartRowArray } from './utils/smartRowArray';
  * rowSelector: 'tbody tr'
  *
  * // Function selector
- * rowSelector: (root) => root.locator('[role="row"]')
+ * headerSelector: (root) => root.locator('[role="columnheader"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
 /**
@@ -28,10 +28,13 @@ export type FilterValue = string | RegExp | number | ((cell: Locator) => Locator
  */
 export type GetCellLocatorFn = (args: {
     row: Locator;
+    /** The root locator passed to useTable(). Useful for re-querying stale row locators. */
+    root: Locator;
     columnName: string;
     columnIndex: number;
     rowIndex?: number;
     page: Page;
+    config: FinalTableConfig<any>;
 }) => Locator;
 /**
  * Hook called before each cell value is read in toJSON (and columnOverrides.read).
@@ -68,6 +71,102 @@ export type GetActiveCellFn = (args: TableContext) => Promise<{
     columnName?: string;
     locator: Locator;
 } | null>;
+/**
+ * Viewport oracle strategies for virtualized tables.
+ *
+ * These tell the library *what is currently in the DOM* rather than *how to move*.
+ * When present, the cell-reading engine uses them to jump directly to a target
+ * row/column instead of stepping blindly with navigation primitives.
+ *
+ * This is the primary fix for the 2D scroll hazard: scrolling right to bring a
+ * column into view can knock rows out of the vertical viewport (and vice versa).
+ * With `getVisibleRowRange` the engine detects this and calls `scrollToRow` to
+ * restore the row before reading — eliminating the hazard without polling loops.
+ *
+ * All members are optional. Supply whichever the underlying grid exposes:
+ * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.
+ * - Scroll primitives alone enable direct jumps without range awareness.
+ * - Both together give the most reliable, fastest path.
+ *
+ * @example
+ * // MUI DataGrid via apiRef
+ * strategies: {
+ *   viewport: {
+ *     getVisibleRowRange: async ({ root }) =>
+ *       root.evaluate(el => {
+ *         const api = (el as any).__muiDataGrid__;
+ *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };
+ *       }),
+ *     scrollToRow: async ({ root }, rowIndex) =>
+ *       root.evaluate((el, idx) =>
+ *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),
+ *     scrollToColumn: async ({ root }, colIndex) =>
+ *       root.evaluate((el, idx) =>
+ *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),
+ *   }
+ * }
+ *
+ * @example
+ * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)
+ * strategies: {
+ *   viewport: {
+ *     getVisibleRowRange: async ({ root }) =>
+ *       root.evaluate(el => {
+ *         const rows = [...el.querySelectorAll('[role="row"][aria-rowindex]')];
+ *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);
+ *         return { first: Math.min(...idxs), last: Math.max(...idxs) };
+ *       }),
+ *   }
+ * }
+ */
+export interface ViewportStrategy {
+    /**
+     * Returns the 0-based index range of rows currently rendered in the DOM.
+     * Used to detect when a target row has been scrolled out of view and needs recovery.
+     */
+    getVisibleRowRange?: (context: TableContext) => Promise<{
+        first: number;
+        last: 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.
+     */
+    getVisibleColumnRange?: (context: TableContext) => Promise<{
+        first: number;
+        last: number;
+    }>;
+    /**
+     * Scrolls or jumps directly to make a row visible by 0-based index.
+     * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.
+     */
+    scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;
+    /**
+     * Scrolls or jumps directly to make a column visible by 0-based index.
+     * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.
+     */
+    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.
+     */
+    disableCache?: boolean;
+}
+/**
+ * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.
+ *
+ * Extends all standard Locator methods (click, isVisible, etc.).
+ */
+export type SmartCell = Locator & {
+    /**
+     * Scrolls/paginates to bring this specific cell into view using the configured strategies.
+     * Useful when the grid is horizontally virtualized and the column must be scrolled
+     * into view before it can be interacted with or read.
+     */
+    bringIntoView(): Promise<void>;
+};
 /**
  * SmartRow - A Playwright Locator with table-aware methods.
  *
@@ -90,12 +189,13 @@ export type SmartRow<T = any> = Locator & {
     /**
      * Get a cell locator by column name.
      * @param column - Column name (case-sensitive)
-     * @returns Locator for the cell
+     * @returns SmartCell (Locator + bringIntoView)
      * @example
      * const emailCell = row.getCell('Email');
+     * await emailCell.bringIntoView();
      * await expect(emailCell).toHaveText('john@example.com');
      */
-    getCell(column: string): Locator;
+    getCell(column: string): SmartCell;
     /**
      * Extract all cell data as a key-value object.
      * @param options - Optional configuration
@@ -113,8 +213,9 @@ export type SmartRow<T = any> = Locator & {
     }): Promise<T>;
     /**
      * Scrolls/paginates to bring this row into view.
-     * Only works if rowIndex is known (e.g., from getRowByIndex).
-     * @throws Error if rowIndex is unknown
+     * Works when row position metadata is known (e.g., from getRowByIndex, findRow,
+     * findRows, filter, or async iteration).
+     * @throws Error if row position metadata is unknown
      */
     bringIntoView(): Promise<void>;
     /**
@@ -211,6 +312,13 @@ export interface PaginationPrimitives {
     goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;
     /** Jump to first page / scroll to top */
     goToFirst?: (context: TableContext) => Promise<boolean>;
+    /** Jump to last page / scroll to bottom */
+    goToLast?: (context: TableContext) => Promise<boolean>;
+    /**
+     * Fetch the total number of pages currently available.
+     * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).
+     */
+    getTotalPages?: (context: TableContext) => Promise<number | null>;
     /**
      * Jump to specific page index (0-indexed).
      * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6–14).
@@ -221,6 +329,17 @@ export interface PaginationPrimitives {
     nextBulkPages?: number;
     /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
     previousBulkPages?: number;
+    /**
+     * Called once during init() to sync the library's page counter with the actual DOM state.
+     * Use when a table may open on a page other than the first (e.g. a deep-linked URL that
+     * lands on page 5). Returns a 0-indexed page number.
+     * @example
+     * detectCurrentPage: async (root) => {
+     *   const text = await root.locator('[aria-current="page"]').textContent();
+     *   return parseInt(text ?? '1') - 1;
+     * }
+     */
+    detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;
 }
 export type PaginationStrategy = PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
@@ -319,6 +438,17 @@ export interface TableStrategies {
      * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.
      */
     loading?: LoadingStrategy;
+    /**
+     * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
+     * Braintrust-style grids where both rows and columns are virtualized simultaneously).
+     *
+     * When present, the cell-reading engine uses these to jump directly to the target
+     * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can
+     * knock rows out of the vertical viewport, and vice versa).
+     *
+     * Completely optional and additive — existing `navigation` primitives remain the fallback.
+     */
+    viewport?: ViewportStrategy;
 }
 export interface TableConfig<T = any> {
     /** Selector for the table headers */
@@ -472,6 +602,24 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Navigates to a specific column using the configured CellNavigationStrategy.
      */
     scrollToColumn: (columnName: string) => Promise<void>;
+    /**
+     * Counts the number of rows currently on the page.
+     * Does not paginate.
+     */
+    countRows: () => Promise<number>;
+    /**
+     * Iterates over rows and extracts the value of a single column.
+     * More efficient than map + toJSON for single-column extraction.
+     * @param columnName - The name of the column to extract
+     * @param options - Iteration options
+     */
+    mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;
+    /**
+     * 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
+     */
+    getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;
     /**
      * Resets the table state (clears cache, flags) and invokes the onReset strategy.
      */