@rickcedwhat/playwright-smart-table 4.0.0 → 5.0.0

package/dist/types.d.ts

@@ -1,4 +1,13 @@
 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);
 /**
  * Function to get a cell locator given row, column info.
@@ -21,24 +30,67 @@ export type GetActiveCellFn = (args: TableContext) => Promise<{
     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 & {
-    getRequestIndex(): number | undefined;
+    /** 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;
+    /**
+     * 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.
+     * Only works if rowIndex is known (e.g., from getRowByIndex).
+     * @throws Error if rowIndex is unknown
      */
     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()
+     * 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: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
 };
@@ -191,13 +243,18 @@ export interface TableResult<T = any> {
     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 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?: {
+    getRow: (filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
     }) => SmartRow;
     /**
@@ -206,38 +263,46 @@ export interface TableResult<T = any> {
      * @param index 1-based row index
      * @param options Optional settings including bringIntoView
      */
-    getByRowIndex: (index: number, options?: {
+    getRowByIndex: (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.
+     * 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>;
     /**
-     * Navigates to a specific column using the configured CellNavigationStrategy.
+     * 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.
      */
@@ -308,4 +373,4 @@ export interface TableResult<T = any> {
 /**
  * Restricted table result that excludes methods that shouldn't be called during iteration.
  */
-export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset' | 'getAllRows'>;
+export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;

package/dist/useTable.d.ts

@@ -2,7 +2,7 @@ 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 { CellNavigationStrategies } from './strategies/columns';
 import { ResolutionStrategies } from './strategies/resolution';
 import { Strategies } from './strategies';
 /**
@@ -11,16 +11,9 @@ import { Strategies } from './strategies';
 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 Strategies.Pagination instead */
-export declare const DeprecatedTableStrategies: {
-    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, CellNavigationStrategies, ColumnStrategies, ResolutionStrategies, Strategies };
+export { FillStrategies, HeaderStrategies, CellNavigationStrategies, ResolutionStrategies, Strategies };

package/dist/useTable.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Strategies = exports.ResolutionStrategies = exports.ColumnStrategies = exports.CellNavigationStrategies = exports.HeaderStrategies = exports.FillStrategies = exports.SortingStrategies = exports.DeprecatedTableStrategies = exports.PaginationStrategies = exports.useTable = void 0;
+exports.Strategies = exports.ResolutionStrategies = exports.CellNavigationStrategies = exports.HeaderStrategies = exports.FillStrategies = exports.SortingStrategies = exports.PaginationStrategies = exports.useTable = void 0;
 const typeContext_1 = require("./typeContext");
 const sorting_1 = require("./strategies/sorting");
 const pagination_1 = require("./strategies/pagination");
@@ -19,13 +19,13 @@ const headers_1 = require("./strategies/headers");
 Object.defineProperty(exports, "HeaderStrategies", { enumerable: true, get: function () { return headers_1.HeaderStrategies; } });
 const columns_1 = require("./strategies/columns");
 Object.defineProperty(exports, "CellNavigationStrategies", { enumerable: true, get: function () { return columns_1.CellNavigationStrategies; } });
-Object.defineProperty(exports, "ColumnStrategies", { enumerable: true, get: function () { return columns_1.ColumnStrategies; } });
 const smartRow_1 = require("./smartRow");
 const filterEngine_1 = require("./filterEngine");
 const resolution_1 = require("./strategies/resolution");
 Object.defineProperty(exports, "ResolutionStrategies", { enumerable: true, get: function () { return resolution_1.ResolutionStrategies; } });
 const strategies_1 = require("./strategies");
 Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
+const validation_1 = require("./strategies/validation");
 /**
  * Main hook to interact with a table.
  */
@@ -162,7 +162,8 @@ const useTable = (rootLocator, configOptions = {}) => {
                     page: rootLocator.page(),
                     resolve: resolve
                 };
-                const didLoadMore = yield config.strategies.pagination(context);
+                const paginationResult = yield config.strategies.pagination(context);
+                const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                 if (didLoadMore) {
                     _hasPaginated = true;
                     currentPage++;
@@ -242,7 +243,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         }),
         getHeaders: () => __awaiter(void 0, void 0, void 0, function* () {
             if (!_isInitialized || !_headerMap)
-                throw new Error('Table not initialized. Call await table.init() first.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             return Array.from(_headerMap.keys());
         }),
         getHeaderCell: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
@@ -299,22 +300,22 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return results;
         }),
-        getByRow: (filters, options = { exact: false }) => {
+        getRow: (filters, options = { exact: false }) => {
             if (!_isInitialized || !_headerMap)
-                throw new Error('Table not initialized. Call await table.init() first.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = filterEngine.applyFilters(allRows, filters, _headerMap, options.exact || false, rootLocator.page());
             const rowLocator = matchedRows.first();
             return _makeSmart(rowLocator, _headerMap, 0); // fallback index 0
         },
-        getByRowIndex: (index, options = {}) => {
+        getRowByIndex: (index, options = {}) => {
             if (!_isInitialized || !_headerMap)
-                throw new Error('Table not initialized. Call await table.init() first.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             const rowIndex = index - 1; // Convert 1-based to 0-based
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(rowIndex);
             return _makeSmart(rowLocator, _headerMap, rowIndex);
         },
-        searchForRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+        findRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
             yield _ensureInitialized();
             let row = yield _findRowLocator(filters, options);
             if (!row) {
@@ -322,7 +323,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return _makeSmart(row, _headerMap, 0);
         }),
-        getAllCurrentRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
+        getRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
             yield _ensureInitialized();
             let rowLocators = resolve(config.rowSelector, rootLocator);
             if (options === null || options === void 0 ? void 0 : options.filter) {
@@ -335,22 +336,44 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return smartRows;
         }),
-        getAllRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            console.warn("⚠️ [SmartTable] getAllRows is deprecated. Use getAllCurrentRows instead.");
-            return result.getAllCurrentRows(options);
-        }),
-        generateConfigPrompt: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            const html = yield _getCleanHtml(rootLocator);
-            const separator = "=".repeat(50);
-            const content = `\n${separator}\n🤖 COPY INTO GEMINI/ChatGPT 🤖\n${separator}\nI am using 'playwright-smart-table'.\nTarget Table Locator: ${rootLocator.toString()}\nGenerate config for:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n${separator}\n`;
-            yield _handlePrompt('Smart Table Config', content, options);
-        }),
-        generateStrategyPrompt: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            const container = rootLocator.locator('xpath=..');
-            const html = yield _getCleanHtml(container);
-            const content = `\n==================================================\n🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖\n==================================================\nI need a custom Pagination Strategy for 'playwright-smart-table'.\nContainer HTML:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n`;
-            yield _handlePrompt('Smart Table Strategy', content, options);
+        findRows: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            yield _ensureInitialized();
+            const allRows = [];
+            const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
+            let pageCount = 0;
+            // Collect rows from current page
+            let rowLocators = resolve(config.rowSelector, rootLocator);
+            rowLocators = filterEngine.applyFilters(rowLocators, filters, _headerMap, (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false, rootLocator.page());
+            let rows = yield rowLocators.all();
+            allRows.push(...rows.map((loc, i) => _makeSmart(loc, _headerMap, i)));
+            // Paginate and collect more rows
+            while (pageCount < effectiveMaxPages && config.strategies.pagination) {
+                const paginationResult = yield config.strategies.pagination({
+                    root: rootLocator,
+                    config,
+                    resolve,
+                    page: rootLocator.page()
+                });
+                const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
+                if (!didPaginate)
+                    break;
+                pageCount++;
+                _hasPaginated = true;
+                // Collect rows from new page
+                rowLocators = resolve(config.rowSelector, rootLocator);
+                rowLocators = filterEngine.applyFilters(rowLocators, filters, _headerMap, (_d = options === null || options === void 0 ? void 0 : options.exact) !== null && _d !== void 0 ? _d : false, rootLocator.page());
+                rows = yield rowLocators.all();
+                allRows.push(...rows.map((loc, i) => _makeSmart(loc, _headerMap, i)));
+            }
+            if (options === null || options === void 0 ? void 0 : options.asJSON) {
+                return Promise.all(allRows.map(r => r.toJSON()));
+            }
+            return allRows;
         }),
+        isInitialized: () => {
+            return _isInitialized;
+        },
         sorting: {
             apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
                 yield _ensureInitialized();
@@ -381,12 +404,13 @@ const useTable = (rootLocator, configOptions = {}) => {
                 init: result.init,
                 getHeaders: result.getHeaders,
                 getHeaderCell: result.getHeaderCell,
-                getByRow: result.getByRow,
-                getByRowIndex: result.getByRowIndex,
-                getAllCurrentRows: result.getAllCurrentRows,
+                getRow: result.getRow,
+                getRowByIndex: result.getRowByIndex,
+                findRow: result.findRow,
+                getRows: result.getRows,
+                findRows: result.findRows,
                 getColumnValues: result.getColumnValues,
-                generateConfigPrompt: result.generateConfigPrompt,
-                generateStrategyPrompt: result.generateStrategyPrompt,
+                isInitialized: result.isInitialized,
                 sorting: result.sorting,
                 scrollToColumn: result.scrollToColumn,
                 revalidate: result.revalidate,
@@ -444,6 +468,4 @@ const useTable = (rootLocator, configOptions = {}) => {
 };
 exports.useTable = useTable;
 exports.PaginationStrategies = pagination_1.PaginationStrategies;
-/** @deprecated Use Strategies.Pagination instead */
-exports.DeprecatedTableStrategies = pagination_1.DeprecatedPaginationStrategies;
 exports.SortingStrategies = sorting_1.SortingStrategies;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "4.0.0",
-  "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
+  "version": "5.0.0",
+  "description": "Production-ready table testing for Playwright with smart column-aware locators. Core library with plugin support for custom table implementations.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rickcedwhat/playwright-smart-table.git"