@rickcedwhat/playwright-smart-table 3.1.0 → 4.0.0

package/dist/typeContext.js

@@ -9,16 +9,51 @@ exports.TYPE_CONTEXT = void 0;
 exports.TYPE_CONTEXT = `
 export type Selector = string | ((root: Locator | Page) => Locator);
 
-export type SmartRow = Locator & {
+/**
+ * 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>;
+
+
+export type SmartRow<T = any> = Locator & {
+  getRequestIndex(): number | undefined;
+  rowIndex?: number;
   getCell(column: string): Locator;
-  toJSON(): Promise<Record<string, string>>;
+  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.
    */
-  smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+  bringIntoView(): Promise<void>;
+  /**
+   * Fills the row with data. Automatically detects input types.
+   */
+  fill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
+  /**
+   * Alias for fill() to avoid conflict with Locator.fill()
+   */
+  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 
-export type StrategyContext = TableContext;
+export type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };
 
 /**
  * Defines the contract for a sorting strategy.
@@ -63,50 +98,103 @@ export interface PromptOptions {
   includeTypes?: boolean;
 }
 
-export interface TableConfig {
-  rowSelector?: Selector;
-  headerSelector?: Selector;
-  cellSelector?: Selector;
+export type FillStrategy = (options: {
+  row: SmartRow;
+  columnName: string;
+  value: any;
+  index: number;
+  page: Page;
+  rootLocator: Locator;
+  table: TableResult; // The parent table instance
+  fillOptions?: FillOptions;
+}) => Promise<void>;
+
+export type { HeaderStrategy } from './strategies/headers';
+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.
+ */
+export interface TableConfig {
+  /** Selector for the table headers */
+  headerSelector?: string;
+  /** Selector for the table rows */
+  rowSelector?: string;
+  /** Selector for the cells within a row */
+  cellSelector?: string;
+  /** Number of pages to scan for verification */
   maxPages?: number;
-  /**
-   * Hook to rename columns dynamically.
-   * * @param args.text - The default innerText of the header.
-   * @param args.index - The column index.
-   * @param args.locator - The specific header cell locator.
-   */
+  /** Hook to rename columns dynamically */
   headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;
+  /** Automatically scroll to table on init */
   autoScroll?: boolean;
-  /**
-   * Enable debug mode to log internal state to console.
-   */
+  /** Enable debug logs */
   debug?: boolean;
-  /**
-   * Strategy to reset the table to the initial page.
-   * Called when table.reset() is invoked.
-   */
+  /** Reset hook */
   onReset?: (context: TableContext) => Promise<void>;
+  /** All interaction strategies */
+  strategies?: TableStrategies;
+}
+
+export interface FinalTableConfig extends TableConfig {
+  headerSelector: string;
+  rowSelector: string;
+  cellSelector: string;
+  maxPages: number;
+  autoScroll: boolean;
+  debug: boolean;
+  headerTransformer: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;
+  onReset: (context: TableContext) => Promise<void>;
+  strategies: TableStrategies;
 }
 
-/**
- * Represents the final, resolved table configuration after default values have been applied.
- * All optional properties from TableConfig are now required, except for \`sorting\`.
- */
-export type FinalTableConfig = Required<Omit<TableConfig, 'sorting'>> & {
-  sorting?: SortingStrategy;
-};
 
 export interface FillOptions {
   /**
    * Custom input mappers for specific columns.
    * Maps column names to functions that return the input locator for that cell.
-   * Columns not specified here will use auto-detection.
    */
   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)
@@ -117,23 +205,46 @@ export interface TableResult {
   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: (
-    filters: Record<string, string | RegExp | number>, 
+    filters: Record<string, string | RegExp | number>,
     options?: { exact?: boolean }
   ) => SmartRow;
 
+  /**
+   * 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
+   */
+  getByRowIndex: (
+    index: number,
+    options?: { bringIntoView?: boolean }
+  ) => SmartRow;
+
   /**
    * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
    * Auto-initializes if needed.
    */
   searchForRow: (
-    filters: Record<string, string | RegExp | number>, 
+    filters: Record<string, string | RegExp | number>,
     options?: { exact?: boolean, maxPages?: number }
   ) => Promise<SmartRow>;
 
+  /**
+   * Navigates to a specific column using the configured CellNavigationStrategy.
+   */
+  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[]>;
+
+  /**
+   * @deprecated Use getAllCurrentRows instead. This method will be removed in a future major version.
+   */
   getAllRows: <T extends { asJSON?: boolean }>(
     options?: { filter?: Record<string, any>, exact?: boolean } & T
   ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
@@ -146,6 +257,12 @@ export interface TableResult {
    */
   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.
    */
@@ -197,5 +314,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'>;
+export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset' | 'getAllRows'>;
 `;

package/dist/types.d.ts

@@ -1,14 +1,51 @@
 import type { Locator, Page } from '@playwright/test';
 export type Selector = string | ((root: Locator | Page) => Locator);
-export type SmartRow = Locator & {
+/**
+ * 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>;
+export type SmartRow<T = any> = Locator & {
+    getRequestIndex(): number | undefined;
+    rowIndex?: number;
     getCell(column: string): Locator;
-    toJSON(): Promise<Record<string, string>>;
+    toJSON(options?: {
+        columns?: string[];
+    }): Promise<T>;
+    /**
+     * Scrolls/paginates to bring this row into view.
+     * Only works if rowIndex is known.
+     */
+    bringIntoView(): Promise<void>;
     /**
-     * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
+     * Fills the row with data. Automatically detects input types.
      */
-    smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+    fill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
+    /**
+     * Alias for fill() to avoid conflict with Locator.fill()
+     */
+    smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
+};
+export type StrategyContext = TableContext & {
+    rowLocator?: Locator;
+    rowIndex?: number;
 };
-export type StrategyContext = TableContext;
 /**
  * Defines the contract for a sorting strategy.
  */
@@ -46,51 +83,107 @@ export interface PromptOptions {
     output?: 'console' | 'error';
     includeTypes?: boolean;
 }
-export interface TableConfig {
-    rowSelector?: Selector;
-    headerSelector?: Selector;
-    cellSelector?: Selector;
+export type FillStrategy = (options: {
+    row: SmartRow;
+    columnName: string;
+    value: any;
+    index: number;
+    page: Page;
+    rootLocator: Locator;
+    table: TableResult;
+    fillOptions?: FillOptions;
+}) => Promise<void>;
+export type { HeaderStrategy } from './strategies/headers';
+export type { CellNavigationStrategy } from './strategies/columns';
+import { HeaderStrategy } from './strategies/headers';
+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.
+ */
+export interface TableConfig {
+    /** Selector for the table headers */
+    headerSelector?: string;
+    /** Selector for the table rows */
+    rowSelector?: string;
+    /** Selector for the cells within a row */
+    cellSelector?: string;
+    /** Number of pages to scan for verification */
     maxPages?: number;
-    /**
-     * Hook to rename columns dynamically.
-     * * @param args.text - The default innerText of the header.
-     * @param args.index - The column index.
-     * @param args.locator - The specific header cell locator.
-     */
+    /** Hook to rename columns dynamically */
     headerTransformer?: (args: {
         text: string;
         index: number;
         locator: Locator;
     }) => string | Promise<string>;
+    /** Automatically scroll to table on init */
     autoScroll?: boolean;
-    /**
-     * Enable debug mode to log internal state to console.
-     */
+    /** Enable debug logs */
     debug?: boolean;
-    /**
-     * Strategy to reset the table to the initial page.
-     * Called when table.reset() is invoked.
-     */
+    /** Reset hook */
     onReset?: (context: TableContext) => Promise<void>;
+    /** All interaction strategies */
+    strategies?: TableStrategies;
+}
+export interface FinalTableConfig extends TableConfig {
+    headerSelector: string;
+    rowSelector: string;
+    cellSelector: string;
+    maxPages: number;
+    autoScroll: boolean;
+    debug: boolean;
+    headerTransformer: (args: {
+        text: string;
+        index: number;
+        locator: Locator;
+    }) => string | Promise<string>;
+    onReset: (context: TableContext) => Promise<void>;
+    strategies: TableStrategies;
 }
-/**
- * Represents the final, resolved table configuration after default values have been applied.
- * All optional properties from TableConfig are now required, except for `sorting`.
- */
-export type FinalTableConfig = Required<Omit<TableConfig, 'sorting'>> & {
-    sorting?: SortingStrategy;
-};
 export interface FillOptions {
     /**
      * Custom input mappers for specific columns.
      * Maps column names to functions that return the input locator for that cell.
-     * Columns not specified here will use auto-detection.
      */
     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)
@@ -101,12 +194,21 @@ export interface TableResult {
     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: (filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
     }) => SmartRow;
+    /**
+     * 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
+     */
+    getByRowIndex: (index: number, options?: {
+        bringIntoView?: boolean;
+    }) => SmartRow;
     /**
      * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
      * Auto-initializes if needed.
@@ -115,6 +217,19 @@ export interface TableResult {
         exact?: boolean;
         maxPages?: number;
     }) => Promise<SmartRow>;
+    /**
+     * Navigates to a specific column using the configured CellNavigationStrategy.
+     */
+    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[]>;
+    /**
+     * @deprecated Use getAllCurrentRows instead. This method will be removed in a future major version.
+     */
     getAllRows: <T extends {
         asJSON?: boolean;
     }>(options?: {
@@ -127,6 +242,11 @@ export interface TableResult {
      * 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.
      */
@@ -188,4 +308,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'>;
+export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset' | 'getAllRows'>;

package/dist/useTable.d.ts

@@ -1,25 +1,26 @@
 import type { Locator } from '@playwright/test';
 import { TableConfig, Selector, TableResult, PaginationStrategy } from './types';
+import { FillStrategies } from './strategies/fill';
+import { HeaderStrategies } from './strategies/headers';
+import { CellNavigationStrategies, ColumnStrategies } from './strategies/columns';
+import { ResolutionStrategies } from './strategies/resolution';
+import { Strategies } from './strategies';
 /**
- * A collection of pre-built pagination strategies.
+ * Main hook to interact with a table.
  */
+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;
 };
-/**
- * @deprecated Use `PaginationStrategies` instead. This alias will be removed in a future major version.
- */
-export declare const TableStrategies: {
+/** @deprecated Use Strategies.Pagination instead */
+export declare const DeprecatedTableStrategies: {
     clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
     clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
     infiniteScroll: (timeout?: number) => PaginationStrategy;
 };
-/**
- * A collection of pre-built sorting strategies.
- */
 export declare const SortingStrategies: {
     AriaSort: () => import("./types").SortingStrategy;
 };
-export declare const useTable: (rootLocator: Locator, configOptions?: TableConfig) => TableResult;
+export { FillStrategies, HeaderStrategies, CellNavigationStrategies, ColumnStrategies, ResolutionStrategies, Strategies };