@rickcedwhat/playwright-smart-table 3.2.0 → 5.0.0

package/dist/strategies/validation.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePaginationResult = validatePaginationResult;
+exports.validatePaginationStrategy = validatePaginationStrategy;
+exports.validateSortingStrategy = validateSortingStrategy;
+exports.validateFillStrategy = validateFillStrategy;
+/**
+ * Validates that a pagination strategy returns a boolean.
+ * @param result - The result from a pagination strategy
+ * @param strategyName - Name of the strategy for error messages
+ */
+function validatePaginationResult(result, strategyName = 'Custom Pagination Strategy') {
+    if (typeof result !== 'boolean') {
+        throw new Error(`[${strategyName}] Pagination strategy must return a boolean (true if paginated, false if no more pages). ` +
+            `Received: ${typeof result} (${JSON.stringify(result)})`);
+    }
+    return result;
+}
+/**
+ * Validates that a pagination strategy is properly configured.
+ * @param strategy - The pagination strategy to validate
+ */
+function validatePaginationStrategy(strategy) {
+    if (typeof strategy !== 'function') {
+        throw new Error(`Pagination strategy must be a function. Received: ${typeof strategy}`);
+    }
+    return true;
+}
+/**
+ * Validates that a sorting strategy has the required methods.
+ * @param strategy - The sorting strategy to validate
+ */
+function validateSortingStrategy(strategy) {
+    if (!strategy || typeof strategy !== 'object') {
+        throw new Error(`Sorting strategy must be an object with 'doSort' and 'getSortState' methods. Received: ${typeof strategy}`);
+    }
+    if (typeof strategy.doSort !== 'function') {
+        throw new Error(`Sorting strategy must have a 'doSort' method. Missing or not a function.`);
+    }
+    if (typeof strategy.getSortState !== 'function') {
+        throw new Error(`Sorting strategy must have a 'getSortState' method. Missing or not a function.`);
+    }
+    return true;
+}
+/**
+ * Validates that a fill strategy is properly configured.
+ * @param strategy - The fill strategy to validate
+ */
+function validateFillStrategy(strategy) {
+    if (typeof strategy !== 'function') {
+        throw new Error(`Fill strategy must be a function. Received: ${typeof strategy}`);
+    }
+    return true;
+}

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.js
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\nexport type SmartRow = Locator & {\n  getRequestIndex(): number | undefined; // Helper to get the row index if known\n  rowIndex?: number;\n  getCell(column: string): Locator;\n  toJSON(): Promise<Record<string, string>>;\n  /**\n   * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).\n   */\n  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;\n  /**\n   * Alias for fill() to avoid conflict with Locator.fill() \n   */\n  smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\nexport interface TableContext {\n  root: Locator;\n  config: FinalTableConfig;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport type { HeaderStrategy } from './strategies/headers';\nexport type { ColumnStrategy } from './strategies/columns';\n\n/**\n * Configuration options for useTable.\n */\nexport interface TableConfig {\n  /** Selector for the table headers */\n  headerSelector?: string;\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Strategy for filling forms within the table */\n  fillStrategy?: FillStrategy;\n  /** Strategy for discovering headers */\n  headerStrategy?: HeaderStrategy;\n  /** Strategy for navigating to columns */\n  columnStrategy?: ColumnStrategy;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n\n  /** Pagination Strategy */\n  pagination?: PaginationStrategy;\n  /** Sorting Strategy */\n  sorting?: SortingStrategy;\n  /** \n   * Hook to rename columns dynamically.\n   */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Enable debug logs */\n  debug?: boolean;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /**\n   * Custom resolver for finding a cell. \n   * Overrides cellSelector logic if provided.\n   * Useful for virtualized tables where nth() index doesn't match DOM index.\n  */\n  cellResolver?: (args: { row: Locator, columnName: string, columnIndex: number, rowIndex?: number }) => Locator;\n}\n\nexport interface FinalTableConfig extends TableConfig {\n  headerSelector: string;\n  rowSelector: string;\n  cellSelector: string;\n  fillStrategy: FillStrategy;\n  headerStrategy: HeaderStrategy;\n  columnStrategy: ColumnStrategy;\n  maxPages: number;\n  pagination: PaginationStrategy;\n  autoScroll: boolean;\n  debug: boolean;\n  headerTransformer: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  cellResolver?: (args: { row: Locator, columnName: string, columnIndex: number, rowIndex?: number }) => Locator;\n}\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\nexport interface TableResult {\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getByRow: {\n    (index: number): SmartRow;\n    (\n      filters: Record<string, string | RegExp | number>,\n      options?: { exact?: boolean }\n    ): SmartRow;\n  };\n\n  /**\n   * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).\n   * Auto-initializes if needed.\n   */\n  searchForRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * Manually scrolls to a column using the configured ColumnStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  getAllCurrentRows: <T extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * @deprecated Use getAllCurrentRows instead. This method will be removed in a future major version.\n   */\n  getAllRows: <T extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Scans a specific column across all pages and returns the values.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Iterates through paginated table data, calling the callback for each iteration.\n   * Callback return values are automatically appended to allData, which is returned.\n   */\n  iterateThroughTable: <T = any>(\n    callback: (context: {\n      index: number;\n      isFirst: boolean;\n      isLast: boolean;\n      rows: SmartRow[];\n      allData: T[];\n      table: RestrictedTableResult;\n    }) => T | Promise<T>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      onFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      onLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n    }\n  ) => Promise<T[]>;\n}\n\n/**\n * Restricted table result that excludes methods that shouldn't be called during iteration.\n */\nexport type RestrictedTableResult = Omit<TableResult, 'searchForRow' | 'iterateThroughTable' | 'reset' | 'getAllRows'>;\n";
+export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\nexport interface TableContext {\n  root: Locator;\n  config: FinalTableConfig;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport type { HeaderStrategy } from './strategies/headers';\nexport type { CellNavigationStrategy } from './strategies/columns';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: string | RegExp | number };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Strategy for navigating to specific cells (row + column) */\n  cellNavigation?: CellNavigationStrategy;\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n}\n\n/**\n * Configuration options for useTable.\n */\nexport interface TableConfig {\n  /** Selector for the table headers */\n  headerSelector?: string;\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Enable debug logs */\n  debug?: boolean;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n}\n\nexport interface FinalTableConfig extends TableConfig {\n  headerSelector: string;\n  rowSelector: string;\n  cellSelector: string;\n  maxPages: number;\n  autoScroll: boolean;\n  debug: boolean;\n  headerTransformer: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\nexport interface TableResult<T = any> {\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match, max pages, and asJSON\n   */\n  findRows: <R extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * ASYNC: Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * @param options - Filter and formatting options\n   */\n  getRows: <R extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Scans a specific column across all pages and returns the values.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Iterates through paginated table data, calling the callback for each iteration.\n   * Callback return values are automatically appended to allData, which is returned.\n   */\n  iterateThroughTable: <T = any>(\n    callback: (context: {\n      index: number;\n      isFirst: boolean;\n      isLast: boolean;\n      rows: SmartRow[];\n      allData: T[];\n      table: RestrictedTableResult;\n    }) => T | Promise<T>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      onFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      onLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n    }\n  ) => Promise<T[]>;\n}\n\n/**\n * Restricted table result that excludes methods that shouldn't be called during iteration.\n */\nexport type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;\n";

package/dist/typeContext.js

@@ -7,21 +7,106 @@ exports.TYPE_CONTEXT = void 0;
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
 exports.TYPE_CONTEXT = `
+/**
+ * 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; // Helper to get the row index if known
+/**
+ * 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>>;
+
+  /**
+   * 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>;
+
   /**
-   * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
+   * 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; rowIndex?: number };
@@ -81,7 +166,44 @@ export type FillStrategy = (options: {
 }) => Promise<void>;
 
 export type { HeaderStrategy } from './strategies/headers';
-export type { ColumnStrategy } from './strategies/columns';
+export type { 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.
@@ -93,22 +215,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, locator: Locator }) => string | Promise<string>;
   /** Automatically scroll to table on init */
   autoScroll?: boolean;
@@ -116,30 +225,23 @@ 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: { text: string, index: number, 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 {
   /**
    * Custom input mappers for specific columns.
@@ -148,61 +250,89 @@ 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)
    */
   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
    */
-  searchForRow: (
+  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
+   */
+  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 { asJSON?: boolean }>(
-    options?: { filter?: Record<string, any>, exact?: boolean } & T
-  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+  findRows: <R extends { asJSON?: boolean }>(
+    filters: Record<string, string | RegExp | number>,
+    options?: { exact?: boolean, maxPages?: number } & R
+  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
 
   /**
-   * @deprecated Use getAllCurrentRows instead. This method will be removed in a future major version.
+   * Navigates to a specific column using the configured CellNavigationStrategy.
    */
-  getAllRows: <T extends { asJSON?: boolean }>(
-    options?: { filter?: Record<string, any>, exact?: boolean } & T
-  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+  scrollToColumn: (columnName: string) => Promise<void>;
 
-  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
-  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;
+  /**
+   * 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
+   */
+  getRows: <R extends { asJSON?: boolean }>(
+    options?: { filter?: Record<string, any>, exact?: boolean } & 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.
    */
@@ -254,5 +384,5 @@ 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'>;
 `;