@rickcedwhat/playwright-smart-table 6.18.0 → 6.20.0

package/dist/types.d.ts

@@ -10,6 +10,15 @@ import type { SmartRowArray } from './utils/smartRowArray';
  * headerSelector: (root) => root.locator('[role="columnheader"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
+/**
+ * Return type for `resolveRowIndex`. A plain number gives the logical index only;
+ * `{ index, selector }` additionally provides a CSS selector the library uses to
+ * build a self-healing row locator that survives virtual-scroll DOM recycling.
+ */
+export type RowIndexResult = number | {
+    index: number;
+    selector: string;
+};
 /**
  * Value used to filter rows.
  * - string/number/RegExp: filter by text content of the cell.
@@ -157,6 +166,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 +254,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.
@@ -265,6 +290,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.
+     * @param column - Column name (case-sensitive)
+     * @returns The column value as a string
+     */
+    getValue(column: string): Promise<string>;
     /**
      * Returns whether the row exists in the DOM (i.e. is not a sentinel row).
      */
@@ -383,12 +414,45 @@ 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 SyntheticColumnDef<T = any> {
+    compute: (row: SmartRow<T>) => Promise<string | number> | string | number;
+}
 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.
@@ -466,6 +530,12 @@ 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 */
+    sortStabilizationTimeout?: number;
+    /** Polling interval (ms) while waiting for sort stabilization. @default 100 */
+    sortStabilizationPollInterval?: number;
+    /** Fallback delay (ms) after sort when no isTableLoading is configured. @default 200 */
+    sortStabilizationFallbackDelay?: number;
 }
 /**
  * Organized container for all table interaction strategies.
@@ -513,14 +583,20 @@ export interface TableStrategies {
      *
      * Return `undefined` to fall back to DOM position.
      *
+     * When the index maps to a DOM attribute, return `{ index, selector }` instead of
+     * a plain number. The library uses the CSS selector to build a **self-healing row
+     * locator** that re-queries the DOM on every action — surviving virtual-scroll
+     * recycling for `getCell`, `smartFill`, and `toJSON` without manual re-pinning.
+     *
      * @example
-     * // MUI DataGrid: read the global monotone counter from the attribute
+     * // MUI DataGrid: self-healing via data-rowindex attribute
      * resolveRowIndex: async (row) => {
      *   const v = await row.getAttribute('data-rowindex').catch(() => null);
-     *   return v !== null && !isNaN(Number(v)) ? Number(v) : undefined;
+     *   if (v === null || isNaN(Number(v))) return undefined;
+     *   return { index: Number(v), selector: `[data-rowindex="${v}"]` };
      * }
      */
-    resolveRowIndex?: (row: Locator) => Promise<number | undefined>;
+    resolveRowIndex?: (row: Locator) => Promise<RowIndexResult | undefined>;
     /**
      * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
      * Braintrust-style grids where both rows and columns are virtualized simultaneously).
@@ -558,7 +634,7 @@ export interface TableConfig<T = any> {
     autoScroll?: boolean;
     /** Debug options for development and troubleshooting */
     debug?: DebugConfig;
-    /** Reset hook */
+    /** Hook called after reset completes (after goToFirst, cache clear, and autoInit). */
     onReset?: (context: TableContext) => Promise<void>;
     /** All interaction strategies */
     strategies?: TableStrategies;
@@ -567,6 +643,19 @@ export interface TableConfig<T = any> {
      * Overrides both default extraction (toJSON) and filling (smartFill) logic.
      */
     columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
+    /**
+     * Computed columns with no DOM presence. Each key becomes a virtual column name
+     * available in `toJSON()`, `getValue()`, and `findRow()`/`findRows()` filters.
+     * The `compute` function receives the full SmartRow and must only read real or
+     * override columns (no chaining between synthetics).
+     */
+    syntheticColumns?: Record<string, SyntheticColumnDef<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);
@@ -595,9 +684,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;
@@ -651,6 +748,12 @@ 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>;
     /**
@@ -670,8 +773,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * 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. To iterate virtualized rows by logical identity, use `map` /
-     * `findRows` (with a `dedupe` strategy) instead.
+     * 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.
@@ -679,6 +783,24 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * @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.
@@ -705,10 +827,14 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     scrollToColumn: (columnName: string) => Promise<void>;
     /**
-     * Counts the number of rows currently on the page.
-     * Does not paginate.
+     * Counts the number of rows, optionally filtered.
+     * Without arguments, counts all rows. With filters, counts only matching rows.
+     * Paginates when pagination is configured.
      */
-    countRows: () => Promise<number>;
+    countRows: (filters?: Record<string, FilterValue>, options?: {
+        exact?: boolean;
+        maxPages?: number;
+    }) => Promise<number>;
     /**
      * Iterates over rows and extracts the value of a single column.
      * More efficient than map + toJSON for single-column extraction.
@@ -723,7 +849,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;
     /**
-     * Resets the table state (clears cache, flags) and invokes the onReset strategy.
+     * Resets the table: calls goToFirst (if configured), clears cache, re-inits headers, then calls onReset.
      */
     reset: () => Promise<void>;
     /**