@rickcedwhat/playwright-smart-table 5.3.0 → 6.0.0

package/dist/src/strategies/sorting.d.ts

@@ -0,0 +1,12 @@
+import type { SortingStrategy } from '../types';
+/**
+ * A collection of pre-built sorting strategies.
+ */
+export declare const SortingStrategies: {
+    /**
+     * A sorting strategy that interacts with column headers based on ARIA attributes.
+     * - `doSort`: Clicks the header repeatedly until the desired `aria-sort` state is achieved.
+     * - `getSortState`: Reads the `aria-sort` attribute from the header.
+     */
+    AriaSort: () => SortingStrategy;
+};

package/dist/src/strategies/sorting.js

@@ -0,0 +1,68 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SortingStrategies = void 0;
+/**
+ * A collection of pre-built sorting strategies.
+ */
+exports.SortingStrategies = {
+    /**
+     * A sorting strategy that interacts with column headers based on ARIA attributes.
+     * - `doSort`: Clicks the header repeatedly until the desired `aria-sort` state is achieved.
+     * - `getSortState`: Reads the `aria-sort` attribute from the header.
+     */
+    AriaSort: () => {
+        return {
+            doSort(_a) {
+                return __awaiter(this, arguments, void 0, function* ({ columnName, direction, context }) {
+                    const { resolve, config, root } = context;
+                    const headerLoc = resolve(config.headerSelector, root);
+                    const headers = yield headerLoc.all();
+                    const headerTexts = yield Promise.all(headers.map(h => h.innerText()));
+                    const columnIndex = headerTexts.findIndex(text => text.trim() === columnName);
+                    if (columnIndex === -1) {
+                        throw new Error(`[AriaSort] Header with text "${columnName}" not found.`);
+                    }
+                    const targetHeader = headers[columnIndex];
+                    // Click repeatedly to cycle through sort states
+                    for (let i = 0; i < 3; i++) { // Max 3 clicks to prevent infinite loops (none -> asc -> desc)
+                        const currentState = yield targetHeader.getAttribute('aria-sort');
+                        const mappedState = currentState === 'ascending' ? 'asc' : currentState === 'descending' ? 'desc' : 'none';
+                        if (mappedState === direction) {
+                            return; // Desired state achieved
+                        }
+                        yield targetHeader.click();
+                    }
+                    throw new Error(`[AriaSort] Could not achieve sort direction "${direction}" for column "${columnName}" after 3 clicks.`);
+                });
+            },
+            getSortState(_a) {
+                return __awaiter(this, arguments, void 0, function* ({ columnName, context }) {
+                    const { resolve, config, root } = context;
+                    const headerLoc = resolve(config.headerSelector, root);
+                    const headers = yield headerLoc.all();
+                    const headerTexts = yield Promise.all(headers.map(h => h.innerText()));
+                    const columnIndex = headerTexts.findIndex(text => text.trim() === columnName);
+                    if (columnIndex === -1) {
+                        return 'none'; // Header not found, so it's not sorted
+                    }
+                    const targetHeader = headers[columnIndex];
+                    const ariaSort = yield targetHeader.getAttribute('aria-sort');
+                    if (ariaSort === 'ascending')
+                        return 'asc';
+                    if (ariaSort === 'descending')
+                        return 'desc';
+                    return 'none';
+                });
+            },
+        };
+    },
+};

package/dist/src/strategies/stabilization.d.ts

@@ -0,0 +1,29 @@
+import { TableContext } from '../types';
+/**
+ * A Stabilization Strategy determines when a table has "settled" after an action.
+ * It wraps the action to capture state before and after.
+ */
+export type StabilizationStrategy = (context: TableContext, action: () => Promise<void>) => Promise<boolean>;
+export declare const StabilizationStrategies: {
+    /**
+     * Waits for the visible text of the table rows to change.
+     */
+    contentChanged: (options?: {
+        scope?: "all" | "first";
+        timeout?: number;
+    }) => StabilizationStrategy;
+    /**
+     * Waits for the total number of rows to strictly increase.
+     */
+    rowCountIncreased: (options?: {
+        timeout?: number;
+    }) => StabilizationStrategy;
+    /**
+     * Waits for a specific network condition or spinner to disappear.
+     * Useful for tables that have explicit loading states but might not change content immediately.
+     */
+    networkIdle: (options?: {
+        spinnerSelector?: string;
+        timeout?: number;
+    }) => StabilizationStrategy;
+};

package/dist/src/strategies/stabilization.js

@@ -0,0 +1,91 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StabilizationStrategies = void 0;
+exports.StabilizationStrategies = {
+    /**
+     * Waits for the visible text of the table rows to change.
+     */
+    contentChanged: (options = {}) => {
+        return (_a, action_1) => __awaiter(void 0, [_a, action_1], void 0, function* ({ root, config, resolve, page }, action) {
+            var _b, _c;
+            const rows = resolve(config.rowSelector, root);
+            const timeout = (_b = options.timeout) !== null && _b !== void 0 ? _b : 5000;
+            const scope = (_c = options.scope) !== null && _c !== void 0 ? _c : 'all';
+            // Helper to get fingerprint
+            const getFingerprint = () => __awaiter(void 0, void 0, void 0, function* () {
+                if (scope === 'first') {
+                    return yield rows.first().innerText().catch(() => '');
+                }
+                const allText = yield rows.allInnerTexts();
+                return allText.join('|');
+            });
+            // 1. Capture Before
+            const beforeFingerprint = yield getFingerprint();
+            // 2. Perform Action
+            yield action();
+            // 3. Wait for Change
+            const startTime = Date.now();
+            while (Date.now() - startTime < timeout) {
+                const afterFingerprint = yield getFingerprint();
+                if (afterFingerprint !== beforeFingerprint) {
+                    return true;
+                }
+                yield page.waitForTimeout(100);
+            }
+            return false;
+        });
+    },
+    /**
+     * Waits for the total number of rows to strictly increase.
+     */
+    rowCountIncreased: (options = {}) => {
+        return (_a, action_1) => __awaiter(void 0, [_a, action_1], void 0, function* ({ root, config, resolve, page }, action) {
+            var _b;
+            const rows = resolve(config.rowSelector, root);
+            const timeout = (_b = options.timeout) !== null && _b !== void 0 ? _b : 5000;
+            const beforeCount = yield rows.count();
+            yield action();
+            const startTime = Date.now();
+            while (Date.now() - startTime < timeout) {
+                const afterCount = yield rows.count();
+                if (afterCount > beforeCount) {
+                    return true;
+                }
+                yield page.waitForTimeout(100);
+            }
+            return false;
+        });
+    },
+    /**
+     * Waits for a specific network condition or spinner to disappear.
+     * Useful for tables that have explicit loading states but might not change content immediately.
+     */
+    networkIdle: (options = {}) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, page, resolve }) {
+            var _b;
+            const timeout = (_b = options.timeout) !== null && _b !== void 0 ? _b : 5000;
+            if (options.spinnerSelector) {
+                const spinner = resolve(options.spinnerSelector, root);
+                try {
+                    yield spinner.waitFor({ state: 'detached', timeout });
+                    return true;
+                }
+                catch (_c) {
+                    return false;
+                }
+            }
+            // Fallback to simple wait if no selector
+            yield page.waitForTimeout(500);
+            return true;
+        });
+    }
+};

package/dist/src/strategies/validation.d.ts

@@ -0,0 +1,22 @@
+import type { PaginationStrategy, SortingStrategy, FillStrategy } from '../types';
+/**
+ * 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
+ */
+export declare function validatePaginationResult(result: any, strategyName?: string): boolean;
+/**
+ * Validates that a pagination strategy is properly configured.
+ * @param strategy - The pagination strategy to validate
+ */
+export declare function validatePaginationStrategy(strategy: any): strategy is PaginationStrategy;
+/**
+ * Validates that a sorting strategy has the required methods.
+ * @param strategy - The sorting strategy to validate
+ */
+export declare function validateSortingStrategy(strategy: any): strategy is SortingStrategy;
+/**
+ * Validates that a fill strategy is properly configured.
+ * @param strategy - The fill strategy to validate
+ */
+export declare function validateFillStrategy(strategy: any): strategy is FillStrategy;

package/dist/src/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/src/strategies/virtualizedPagination.d.ts

@@ -0,0 +1,32 @@
+import { PaginationStrategy } from '../types';
+/**
+ * Strategies for handling virtualized pagination where:
+ * 1. The total row count might not change (DOM recycling).
+ * 2. We need to check for *new content* appearing to confirm pagination success.
+ */
+export declare const virtualizedInfiniteScroll: (options?: {
+    /** Selector for the scrollable container. Defaults to table root. */
+    scrollTarget?: string;
+    /** Amount to scroll in pixels. Default 500. */
+    scrollAmount?: number;
+    /** Timeout to wait for content stability. Default 500ms. */
+    stabilityTimeout?: number;
+    /** Max retries to detect content change. Default 3. */
+    retries?: number;
+    /** force use of JS scrollTop property instead of mouse wheel. Default: false */
+    useJsScroll?: boolean;
+}) => PaginationStrategy;
+export declare const VirtualizedPaginationStrategies: {
+    virtualInfiniteScroll: (options?: {
+        /** Selector for the scrollable container. Defaults to table root. */
+        scrollTarget?: string;
+        /** Amount to scroll in pixels. Default 500. */
+        scrollAmount?: number;
+        /** Timeout to wait for content stability. Default 500ms. */
+        stabilityTimeout?: number;
+        /** Max retries to detect content change. Default 3. */
+        retries?: number;
+        /** force use of JS scrollTop property instead of mouse wheel. Default: false */
+        useJsScroll?: boolean;
+    }) => PaginationStrategy;
+};

package/dist/src/strategies/virtualizedPagination.js

@@ -0,0 +1,80 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VirtualizedPaginationStrategies = exports.virtualizedInfiniteScroll = void 0;
+/**
+ * Strategies for handling virtualized pagination where:
+ * 1. The total row count might not change (DOM recycling).
+ * 2. We need to check for *new content* appearing to confirm pagination success.
+ */
+const virtualizedInfiniteScroll = (options = {}) => {
+    return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, page, resolve }) {
+        var _b, _c, _d;
+        const scrollTargetLocator = options.scrollTarget
+            ? (typeof options.scrollTarget === 'string' ? root.locator(options.scrollTarget) : resolve(options.scrollTarget, root))
+            : root;
+        // Resolve the rows locator
+        const rows = resolve(config.rowSelector, root);
+        // Helper to get a "fingerprint" of the current visible content
+        const getFingerprint = () => __awaiter(void 0, void 0, void 0, function* () {
+            // We grab all inner texts of the rows as a crude but effective hash
+            // Virtualization replaces row content, so this ensures we detect changes
+            const allText = yield rows.allInnerTexts();
+            return allText.join('|');
+        });
+        const beforeFingerprint = yield getFingerprint();
+        const startScrollTop = yield scrollTargetLocator.evaluate((el) => el.scrollTop).catch(() => 0);
+        // --- Perform Scroll ---
+        const amount = (_b = options.scrollAmount) !== null && _b !== void 0 ? _b : 500;
+        const box = yield scrollTargetLocator.boundingBox();
+        if (options.useJsScroll || !box) {
+            // Fast path: JS Scroll or fallback if no bounding box
+            yield scrollTargetLocator.evaluate((el, y) => {
+                el.scrollTop += y;
+            }, amount);
+        }
+        else {
+            // Realistic path: Mouse Wheel
+            // Move to center of the scroll container
+            yield page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+            yield page.mouse.wheel(0, amount);
+        }
+        // Wait for the virtual list to settle/render new items
+        yield page.waitForTimeout((_c = options.stabilityTimeout) !== null && _c !== void 0 ? _c : 500);
+        // --- Verification ---
+        const endScrollTop = yield scrollTargetLocator.evaluate((el) => el.scrollTop).catch(() => 0);
+        // If we didn't physically scroll (hit bottom or element not scrollable), we're done.
+        // Note: Some virtual lists allow overscroll, so this check isn't 100% foolproof but helpful.
+        if (endScrollTop <= startScrollTop) {
+            // Double check content just in case
+            const afterCheck = yield getFingerprint();
+            const changed = afterCheck !== beforeFingerprint;
+            if (changed)
+                return true;
+            return false;
+        }
+        // Retry loop to allow for async loading/rendering of new rows
+        let retries = (_d = options.retries) !== null && _d !== void 0 ? _d : 3;
+        while (retries > 0) {
+            const afterFingerprint = yield getFingerprint();
+            if (afterFingerprint !== beforeFingerprint) {
+                return true; // Content changed!
+            }
+            yield page.waitForTimeout(200);
+            retries--;
+        }
+        return false; // No change in content detected
+    });
+};
+exports.virtualizedInfiniteScroll = virtualizedInfiniteScroll;
+exports.VirtualizedPaginationStrategies = {
+    virtualInfiniteScroll: exports.virtualizedInfiniteScroll
+};

package/dist/src/typeContext.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 🤖 AUTO-GENERATED FILE. DO NOT EDIT.
+ * 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 = "\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\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | '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 * Strategy to check if the table or rows are loading.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\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  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /** Custom helper to check if a table is fully loaded/ready */\n  isTableLoaded?: (args: TableContext) => Promise<boolean>;\n  /** Custom helper to check if a row is fully loaded/ready */\n  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;\n  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */\n  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;\n  /** Strategy for detecting loading states */\n  loading?: LoadingStrategy;\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, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\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?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => 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\n/**\n * Options for generateConfigPrompt\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  /**\n   * Include TypeScript type definitions in the prompt\n   * @default true\n   */\n  includeTypes?: boolean;\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   * Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * Returns a SmartRowArray which extends Array with a toJSON() helper method.\n   * @param options - Filter options\n   */\n  getRows: (options?: { filter?: Record<string, any>, exact?: boolean }) => Promise<SmartRowArray>;\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: SmartRowArray;\n      allData: T[];\n      table: RestrictedTableResult;\n      batchInfo?: {\n        startIndex: number;\n        endIndex: number;\n        size: number;\n      };\n\n    }) => T | T[] | Promise<T | T[]>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      batchSize?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      beforeFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      afterLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      /**\n       * If true, flattens array results from callback into the main data array.\n       * If false (default), pushes the return value as-is (preserves batching/arrays).\n       */\n      autoFlatten?: boolean;\n    }\n  ) => Promise<T[]>;\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   */\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\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";