@rickcedwhat/playwright-smart-table 3.2.0 → 5.0.0

package/dist/types.d.ts

@@ -1,18 +1,98 @@
 import type { Locator, Page } from '@playwright/test';
+/**
+ * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.
+ * @example
+ * // String selector
+ * rowSelector: 'tbody tr'
+ *
+ * // Function selector
+ * rowSelector: (root) => root.locator('[role="row"]')
+ */
 export type Selector = string | ((root: Locator | Page) => Locator);
-export type SmartRow = Locator & {
-    getRequestIndex(): number | undefined;
+/**
+ * Function to get a cell locator given row, column info.
+ * Replaces the old cellResolver.
+ */
+export type GetCellLocatorFn = (args: {
+    row: Locator;
+    columnName: string;
+    columnIndex: number;
+    rowIndex?: number;
+    page: Page;
+}) => Locator;
+/**
+ * Function to get the currently active/focused cell.
+ * Returns null if no cell is active.
+ */
+export type GetActiveCellFn = (args: TableContext) => Promise<{
+    rowIndex: number;
+    columnIndex: number;
+    columnName?: string;
+    locator: Locator;
+} | null>;
+/**
+ * SmartRow - A Playwright Locator with table-aware methods.
+ *
+ * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.
+ *
+ * @example
+ * const row = table.getRow({ Name: 'John Doe' });
+ * await row.click(); // Standard Locator method
+ * const email = row.getCell('Email'); // Table-aware method
+ * const data = await row.toJSON(); // Extract all row data
+ * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields
+ */
+export type SmartRow<T = any> = Locator & {
+    /** Optional row index (0-based) if known */
     rowIndex?: number;
+    /**
+     * Get a cell locator by column name.
+     * @param column - Column name (case-sensitive)
+     * @returns Locator for the cell
+     * @example
+     * const emailCell = row.getCell('Email');
+     * await expect(emailCell).toHaveText('john@example.com');
+     */
     getCell(column: string): Locator;
-    toJSON(): Promise<Record<string, string>>;
     /**
-     * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
+     * Extract all cell data as a key-value object.
+     * @param options - Optional configuration
+     * @param options.columns - Specific columns to extract (extracts all if not specified)
+     * @returns Promise resolving to row data
+     * @example
+     * const data = await row.toJSON();
+     * // { Name: 'John', Email: 'john@example.com', ... }
+     *
+     * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
+     * // { Name: 'John', Email: 'john@example.com' }
+     */
+    toJSON(options?: {
+        columns?: string[];
+    }): 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
      */
-    fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+    bringIntoView(): Promise<void>;
     /**
-     * Alias for fill() to avoid conflict with Locator.fill()
+     * Intelligently fills form fields in the row.
+     * Automatically detects input types (text, select, checkbox, contenteditable).
+     *
+     * @param data - Column-value pairs to fill
+     * @param options - Optional configuration
+     * @param options.inputMappers - Custom input selectors per column
+     * @example
+     * // Auto-detection
+     * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });
+     *
+     * // Custom input mappers
+     * await row.smartFill(
+     *   { Name: 'John' },
+     *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }
+     * );
      */
-    smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+    smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 export type StrategyContext = TableContext & {
     rowLocator?: Locator;
@@ -66,9 +146,46 @@ export type FillStrategy = (options: {
     fillOptions?: FillOptions;
 }) => Promise<void>;
 export type { HeaderStrategy } from './strategies/headers';
-export type { ColumnStrategy } from './strategies/columns';
+export type { CellNavigationStrategy } from './strategies/columns';
 import { HeaderStrategy } from './strategies/headers';
-import { ColumnStrategy } from './strategies/columns';
+import { CellNavigationStrategy } from './strategies/columns';
+/**
+ * Strategy to resolve column names (string or regex) to their index.
+ */
+export type { ColumnResolutionStrategy } from './strategies/resolution';
+/**
+ * Strategy to filter rows based on criteria.
+ */
+export interface FilterStrategy {
+    apply(options: {
+        rows: Locator;
+        filter: {
+            column: string;
+            value: string | RegExp | number;
+        };
+        colIndex: number;
+        tableContext: TableContext;
+    }): Locator;
+}
+/**
+ * Organized container for all table interaction strategies.
+ */
+export interface TableStrategies {
+    /** Strategy for discovering/scanning headers */
+    header?: HeaderStrategy;
+    /** Strategy for navigating to specific cells (row + column) */
+    cellNavigation?: CellNavigationStrategy;
+    /** Strategy for filling form inputs */
+    fill?: FillStrategy;
+    /** Strategy for paginating through data */
+    pagination?: PaginationStrategy;
+    /** Strategy for sorting columns */
+    sorting?: SortingStrategy;
+    /** Function to get a cell locator */
+    getCellLocator?: GetCellLocatorFn;
+    /** Function to get the currently active/focused cell */
+    getActiveCell?: GetActiveCellFn;
+}
 /**
  * Configuration options for useTable.
  */
@@ -79,21 +196,9 @@ export interface TableConfig {
     rowSelector?: string;
     /** Selector for the cells within a row */
     cellSelector?: string;
-    /** Strategy for filling forms within the table */
-    fillStrategy?: FillStrategy;
-    /** Strategy for discovering headers */
-    headerStrategy?: HeaderStrategy;
-    /** Strategy for navigating to columns */
-    columnStrategy?: ColumnStrategy;
     /** Number of pages to scan for verification */
     maxPages?: number;
-    /** Pagination Strategy */
-    pagination?: PaginationStrategy;
-    /** Sorting Strategy */
-    sorting?: SortingStrategy;
-    /**
-     * Hook to rename columns dynamically.
-     */
+    /** Hook to rename columns dynamically */
     headerTransformer?: (args: {
         text: string;
         index: number;
@@ -105,27 +210,14 @@ export interface TableConfig {
     debug?: boolean;
     /** Reset hook */
     onReset?: (context: TableContext) => Promise<void>;
-    /**
-     * Custom resolver for finding a cell.
-     * Overrides cellSelector logic if provided.
-     * Useful for virtualized tables where nth() index doesn't match DOM index.
-    */
-    cellResolver?: (args: {
-        row: Locator;
-        columnName: string;
-        columnIndex: number;
-        rowIndex?: number;
-    }) => Locator;
+    /** All interaction strategies */
+    strategies?: TableStrategies;
 }
 export interface FinalTableConfig extends TableConfig {
     headerSelector: string;
     rowSelector: string;
     cellSelector: string;
-    fillStrategy: FillStrategy;
-    headerStrategy: HeaderStrategy;
-    columnStrategy: ColumnStrategy;
     maxPages: number;
-    pagination: PaginationStrategy;
     autoScroll: boolean;
     debug: boolean;
     headerTransformer: (args: {
@@ -134,12 +226,7 @@ export interface FinalTableConfig extends TableConfig {
         locator: Locator;
     }) => string | Promise<string>;
     onReset: (context: TableContext) => Promise<void>;
-    cellResolver?: (args: {
-        row: Locator;
-        columnName: string;
-        columnIndex: number;
-        rowIndex?: number;
-    }) => Locator;
+    strategies: TableStrategies;
 }
 export interface FillOptions {
     /**
@@ -148,7 +235,7 @@ export interface FillOptions {
      */
     inputMappers?: Record<string, (cell: Locator) => Locator>;
 }
-export interface TableResult {
+export interface TableResult<T = any> {
     /**
      * Initializes the table by resolving headers. Must be called before using sync methods.
      * @param options Optional timeout for header resolution (default: 3000ms)
@@ -156,51 +243,75 @@ export interface TableResult {
     init(options?: {
         timeout?: number;
     }): Promise<TableResult>;
+    /**
+     * SYNC: Checks if the table has been initialized.
+     * @returns true if init() has been called and completed, false otherwise
+     */
+    isInitialized(): boolean;
     getHeaders: () => Promise<string[]>;
     getHeaderCell: (columnName: string) => Promise<Locator>;
     /**
-     * Finds a row on the current page only. Returns immediately (sync).
+     * Finds a row by filters on the current page only. Returns immediately (sync).
      * Throws error if table is not initialized.
      */
-    getByRow: {
-        (index: number): SmartRow;
-        (filters: Record<string, string | RegExp | number>, options?: {
-            exact?: boolean;
-        }): SmartRow;
-    };
+    getRow: (filters: Record<string, string | RegExp | number>, options?: {
+        exact?: boolean;
+    }) => SmartRow;
     /**
-     * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
-     * Auto-initializes if needed.
+     * Gets a row by 1-based index on the current page.
+     * Throws error if table is not initialized.
+     * @param index 1-based row index
+     * @param options Optional settings including bringIntoView
+     */
+    getRowByIndex: (index: number, options?: {
+        bringIntoView?: boolean;
+    }) => SmartRow;
+    /**
+     * 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
      */
-    searchForRow: (filters: Record<string, string | RegExp | number>, options?: {
+    findRow: (filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
         maxPages?: number;
     }) => Promise<SmartRow>;
     /**
-     * Manually scrolls to a column using the configured ColumnStrategy.
+     * 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
+     * @param options - Search options including exact match, max pages, and asJSON
      */
-    scrollToColumn: (columnName: string) => Promise<void>;
-    getAllCurrentRows: <T extends {
+    findRows: <R extends {
         asJSON?: boolean;
-    }>(options?: {
-        filter?: Record<string, any>;
+    }>(filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
-    } & T) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+        maxPages?: number;
+    } & R) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+    /**
+     * Navigates to a specific column using the configured CellNavigationStrategy.
+     */
+    scrollToColumn: (columnName: string) => Promise<void>;
     /**
-     * @deprecated Use getAllCurrentRows instead. This method will be removed in a future major version.
+     * ASYNC: Gets all rows on the current page only (does not paginate).
+     * Auto-initializes the table if not already initialized.
+     * @param options - Filter and formatting options
      */
-    getAllRows: <T extends {
+    getRows: <R extends {
         asJSON?: boolean;
     }>(options?: {
         filter?: Record<string, any>;
         exact?: boolean;
-    } & T) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
-    generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
-    generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;
+    } & R) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
     /**
      * Resets the table state (clears cache, flags) and invokes the onReset strategy.
      */
     reset: () => Promise<void>;
+    /**
+     * Revalidates the table's structure (headers, columns) without resetting pagination or state.
+     * Useful when columns change visibility or order dynamically.
+     */
+    revalidate: () => Promise<void>;
     /**
      * Scans a specific column across all pages and returns the values.
      */
@@ -262,4 +373,4 @@ export interface TableResult {
 /**
  * Restricted table result that excludes methods that shouldn't be called during iteration.
  */
-export type RestrictedTableResult = Omit<TableResult, 'searchForRow' | 'iterateThroughTable' | 'reset' | 'getAllRows'>;
+export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;

package/dist/useTable.d.ts

@@ -2,22 +2,18 @@ import type { Locator } from '@playwright/test';
 import { TableConfig, Selector, TableResult, PaginationStrategy } from './types';
 import { FillStrategies } from './strategies/fill';
 import { HeaderStrategies } from './strategies/headers';
-import { ColumnStrategies } from './strategies/columns';
+import { CellNavigationStrategies } from './strategies/columns';
+import { ResolutionStrategies } from './strategies/resolution';
+import { Strategies } from './strategies';
 /**
  * Main hook to interact with a table.
  */
-export declare const useTable: (rootLocator: Locator, configOptions?: TableConfig) => TableResult;
+export declare const useTable: <T = any>(rootLocator: Locator, configOptions?: TableConfig) => TableResult<T>;
 export declare const PaginationStrategies: {
     clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
-    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
-    infiniteScroll: (timeout?: number) => PaginationStrategy;
-};
-export declare const TableStrategies: {
-    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
-    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
     infiniteScroll: (timeout?: number) => PaginationStrategy;
 };
 export declare const SortingStrategies: {
     AriaSort: () => import("./types").SortingStrategy;
 };
-export { FillStrategies, HeaderStrategies, ColumnStrategies };
+export { FillStrategies, HeaderStrategies, CellNavigationStrategies, ResolutionStrategies, Strategies };