@rickcedwhat/playwright-smart-table 3.1.0 → 3.2.0

package/README.md

@@ -81,7 +81,7 @@ const table = useTable(page.locator('#example'), {
   headerSelector: 'thead th',
   cellSelector: 'td',
   // Strategy: Tell it how to find the next page
-  pagination: TableStrategies.clickNext(() => 
+  pagination: PaginationStrategies.clickNext(() =>
     page.getByRole('link', { name: 'Next' })
   ),
   maxPages: 5 // Allow scanning up to 5 pages
@@ -127,10 +127,10 @@ If your tests navigate deep into a paginated table, use `.reset()` to return to
 // Navigate deep into the table by searching for a row on a later page
 try {
   await table.searchForRow({ Name: 'Angelica Ramos' });
-} catch (e) {}
+} catch (e) { }
 
 // Reset internal state (and potentially UI) to initial page
-await table.reset(); 
+await table.reset();
 await table.init(); // Re-init after reset
 
 // Now subsequent searches start from the beginning
@@ -147,7 +147,7 @@ Efficiently extract all values from a specific column:
 ```typescript
 // Example from: https://datatables.net/examples/data_sources/dom
 // Quickly grab all text values from the "Office" column
-const offices = await table.getColumnValues('Office'); 
+const offices = await table.getColumnValues('Office');
 expect(offices).toContain('Tokyo');
 expect(offices.length).toBeGreaterThan(0);
 ```
@@ -193,8 +193,6 @@ For edge cases where auto-detection doesn't work (e.g., custom components, multi
 
 <!-- embed: fill-custom-mappers -->
 ```typescript
-const row = table.getByRow({ ID: '1' });
-
 // Use custom input mappers for specific columns
 await row.smartFill({
   Name: 'John Updated',
@@ -231,7 +229,7 @@ const table = useTable(page.locator('.MuiDataGrid-root').first(), {
   rowSelector: '.MuiDataGrid-row',
   headerSelector: '.MuiDataGrid-columnHeader',
   cellSelector: '.MuiDataGrid-cell',
-  pagination: TableStrategies.clickNext(
+  pagination: PaginationStrategies.clickNext(
     (root) => root.getByRole("button", { name: "Go to next page" })
   ),
   maxPages: 5,
@@ -338,15 +336,17 @@ expect(data).toHaveProperty('Position');
 ```
 <!-- /embed: get-by-row-json -->
 
-#### <a name="getallrows"></a>`getAllRows(options?)`
+#### <a name="getallcurrentrows"></a>`getAllCurrentRows(options?)`
+
+**Purpose:** Inclusive retrieval - gets all rows on the current page matching optional filters.
 
-**Purpose:** Inclusive retrieval - gets all rows matching optional filters.
+**Best for:** Checking existence, validating sort order, bulk data extraction on the current page.
 
-**Best for:** Checking existence, validating sort order, bulk data extraction.
+> **Note:** `getAllRows` is deprecated and will be removed in a future major version. Use `getAllCurrentRows` instead. The deprecated method still works for backwards compatibility.
 
 **Type Signature:**
 ```typescript
-getAllRows: <T extends { asJSON?: boolean }>(
+getAllCurrentRows: <T extends { asJSON?: boolean }>(
   options?: { filter?: Record<string, any>, exact?: boolean } & T
 ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
 ```
@@ -355,17 +355,17 @@ getAllRows: <T extends { asJSON?: boolean }>(
 ```typescript
 // Example from: https://datatables.net/examples/data_sources/dom
 // 1. Get ALL rows on the current page
-const allRows = await table.getAllRows();
+const allRows = await table.getAllCurrentRows();
 expect(allRows.length).toBeGreaterThan(0);
 
 // 2. Get subset of rows (Filtering)
-const tokyoUsers = await table.getAllRows({
+const tokyoUsers = await table.getAllCurrentRows({
   filter: { Office: 'Tokyo' }
 });
 expect(tokyoUsers.length).toBeGreaterThan(0);
 
 // 3. Dump data to JSON
-const data = await table.getAllRows({ asJSON: true });
+const data = await table.getAllCurrentRows({ asJSON: true });
 console.log(data); // [{ Name: "Airi Satou", ... }, ...]
 expect(data.length).toBeGreaterThan(0);
 expect(data[0]).toHaveProperty('Name');
@@ -376,7 +376,7 @@ Filter rows with exact match:
 <!-- embed: get-all-rows-exact -->
 ```typescript
 // Get rows with exact match (default is fuzzy/contains match)
-const exactMatches = await table.getAllRows({
+const exactMatches = await table.getAllCurrentRows({
   filter: { Office: 'Tokyo' },
   exact: true // Requires exact string match
 });
@@ -405,7 +405,7 @@ Basic usage:
 ```typescript
 // Example from: https://datatables.net/examples/data_sources/dom
 // Quickly grab all text values from the "Office" column
-const offices = await table.getColumnValues('Office'); 
+const offices = await table.getColumnValues('Office');
 expect(offices).toContain('Tokyo');
 expect(offices.length).toBeGreaterThan(0);
 ```
@@ -560,11 +560,17 @@ A `SmartRow` extends Playwright's `Locator` with table-aware methods.
 <!-- embed-type: SmartRow -->
 ```typescript
 export type SmartRow = Locator & {
+  getRequestIndex(): number | undefined; // Helper to get the row index if known
+  rowIndex?: number;
   getCell(column: string): Locator;
   toJSON(): Promise<Record<string, string>>;
   /**
    * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
    */
+  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+  /**
+   * Alias for fill() to avoid conflict with Locator.fill() 
+   */
   smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 ```
@@ -583,30 +589,70 @@ Configuration options for `useTable()`.
 
 <!-- embed-type: TableConfig -->
 ```typescript
+/**
+   * Output Strategy:
+   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
+   * - 'console': Standard console logs (Default).
+   */
+  output?: 'console' | 'error';
+  includeTypes?: boolean;
+}
+
+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 { ColumnStrategy } from './strategies/columns';
+import { HeaderStrategy } from './strategies/headers';
+import { ColumnStrategy } from './strategies/columns';
+
+/**
+ * Configuration options for useTable.
+ */
 export interface TableConfig {
-  rowSelector?: Selector;
-  headerSelector?: Selector;
-  cellSelector?: Selector;
+  /** Selector for the table headers */
+  headerSelector?: string;
+  /** Selector for the table rows */
+  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;
-  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.
    */
   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>;
+  /**
+   * 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;
 }
 ```
 <!-- /embed-type: TableConfig -->

package/dist/strategies/columns.d.ts

@@ -0,0 +1,30 @@
+import { StrategyContext } from '../types';
+/**
+ * Defines the contract for a column navigation strategy.
+ * It is responsible for ensuring a specific column is visible/focused,
+ * typically by scrolling or navigating to it.
+ */
+export type ColumnStrategy = (context: StrategyContext & {
+    column: string;
+    index: number;
+    rowIndex?: number;
+}) => Promise<void>;
+export declare const ColumnStrategies: {
+    /**
+     * Default strategy: Assumes column is accessible or standard scrolling works.
+     * No specific action taken other than what Playwright's default locator handling does.
+     */
+    default: () => Promise<void>;
+    /**
+     * Strategy that clicks into the table to establish focus and then uses the Right Arrow key
+     * to navigate to the target column index.
+     *
+     * Useful for canvas-based grids like Glide where DOM scrolling might not be enough for interaction
+     * or where keyboard navigation is the primary way to move focus.
+     */
+    keyboard: (context: StrategyContext & {
+        column: string;
+        index: number;
+        rowIndex?: number;
+    }) => Promise<void>;
+};

package/dist/strategies/columns.js

@@ -0,0 +1,53 @@
+"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.ColumnStrategies = void 0;
+exports.ColumnStrategies = {
+    /**
+     * Default strategy: Assumes column is accessible or standard scrolling works.
+     * No specific action taken other than what Playwright's default locator handling does.
+     */
+    default: () => __awaiter(void 0, void 0, void 0, function* () {
+        // No-op
+    }),
+    /**
+     * Strategy that clicks into the table to establish focus and then uses the Right Arrow key
+     * to navigate to the target column index.
+     *
+     * Useful for canvas-based grids like Glide where DOM scrolling might not be enough for interaction
+     * or where keyboard navigation is the primary way to move focus.
+     */
+    keyboard: (context) => __awaiter(void 0, void 0, void 0, function* () {
+        const { root, page, index, rowLocator, rowIndex } = context;
+        if (typeof rowIndex !== 'number') {
+            throw new Error('Row index is required for keyboard navigation');
+        }
+        console.log(`[ColumnStrat:keyboard] Using Row Index Navigation: Row ${rowIndex}, Col ${index}`);
+        yield root.focus();
+        yield page.waitForTimeout(200);
+        // Robust Navigation:
+        // 1. Jump to Top-Left (Reset) - Sequence for Cross-OS (Mac/Windows)
+        yield page.keyboard.press('Control+Home');
+        yield page.keyboard.press('Meta+ArrowUp'); // Mac Go-To-Top
+        yield page.keyboard.press('Home'); // Ensure start of row
+        yield page.waitForTimeout(300);
+        // 2. Move Down to Target Row
+        for (let i = 0; i < rowIndex; i++) {
+            yield page.keyboard.press('ArrowDown');
+        }
+        // 3. Move Right to Target Column
+        for (let i = 0; i < index; i++) {
+            yield page.keyboard.press('ArrowRight');
+        }
+        yield page.waitForTimeout(100);
+        yield page.waitForTimeout(100);
+    })
+};

package/dist/strategies/fill.d.ts

@@ -0,0 +1,7 @@
+import type { FillStrategy } from '../types';
+export declare const FillStrategies: {
+    /**
+     * Default strategy: Detects input type and fills accordingly (Text, Select, Checkbox, ContentEditable).
+     */
+    default: ({ row, columnName, value, fillOptions }: Parameters<FillStrategy>[0]) => Promise<void>;
+};

package/dist/strategies/fill.js

@@ -0,0 +1,88 @@
+"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.FillStrategies = void 0;
+exports.FillStrategies = {
+    /**
+     * Default strategy: Detects input type and fills accordingly (Text, Select, Checkbox, ContentEditable).
+     */
+    default: (_a) => __awaiter(void 0, [_a], void 0, function* ({ row, columnName, value, fillOptions }) {
+        var _b;
+        const cell = row.getCell(columnName);
+        // Use custom input mapper for this column if provided, otherwise auto-detect
+        let inputLocator;
+        if ((_b = fillOptions === null || fillOptions === void 0 ? void 0 : fillOptions.inputMappers) === null || _b === void 0 ? void 0 : _b[columnName]) {
+            inputLocator = fillOptions.inputMappers[columnName](cell);
+        }
+        else {
+            // Auto-detect input type
+            // Check for text input
+            const textInput = cell.locator('input[type="text"], input:not([type]), textarea').first();
+            const textInputCount = yield textInput.count().catch(() => 0);
+            // Check for select
+            const select = cell.locator('select').first();
+            const selectCount = yield select.count().catch(() => 0);
+            // Check for checkbox/radio
+            const checkbox = cell.locator('input[type="checkbox"], input[type="radio"], [role="checkbox"]').first();
+            const checkboxCount = yield checkbox.count().catch(() => 0);
+            // Check for contenteditable or div-based inputs
+            const contentEditable = cell.locator('[contenteditable="true"]').first();
+            const contentEditableCount = yield contentEditable.count().catch(() => 0);
+            // Determine which input to use (prioritize by commonality)
+            if (textInputCount > 0 && selectCount === 0 && checkboxCount === 0) {
+                inputLocator = textInput;
+            }
+            else if (selectCount > 0) {
+                inputLocator = select;
+            }
+            else if (checkboxCount > 0) {
+                inputLocator = checkbox;
+            }
+            else if (contentEditableCount > 0) {
+                inputLocator = contentEditable;
+            }
+            else if (textInputCount > 0) {
+                // Fallback to text input even if others exist
+                inputLocator = textInput;
+            }
+            else {
+                // No input found - try to click the cell itself (might trigger an editor)
+                inputLocator = cell;
+            }
+        }
+        // Fill based on value type and input type
+        const inputTag = yield inputLocator.evaluate((el) => el.tagName.toLowerCase()).catch(() => 'unknown');
+        const inputType = yield inputLocator.getAttribute('type').catch(() => null);
+        const isContentEditable = yield inputLocator.getAttribute('contenteditable').catch(() => null);
+        // console.log(`[SmartTable] Filling "${columnName}" with value "${value}" (input: ${inputTag}, type: ${inputType})`);
+        if (inputType === 'checkbox' || inputType === 'radio') {
+            // Boolean value for checkbox/radio
+            const shouldBeChecked = Boolean(value);
+            const isChecked = yield inputLocator.isChecked().catch(() => false);
+            if (isChecked !== shouldBeChecked) {
+                yield inputLocator.click();
+            }
+        }
+        else if (inputTag === 'select') {
+            // Select dropdown
+            yield inputLocator.selectOption(String(value));
+        }
+        else if (isContentEditable === 'true') {
+            // Contenteditable div
+            yield inputLocator.click();
+            yield inputLocator.fill(String(value));
+        }
+        else {
+            // Text input, textarea, or generic
+            yield inputLocator.fill(String(value));
+        }
+    })
+};

package/dist/strategies/headers.d.ts

@@ -0,0 +1,29 @@
+import { StrategyContext } from '../types';
+/**
+ * Defines the contract for a header retrieval strategy.
+ * Returns a list of unique header names found in the table.
+ */
+export type HeaderStrategy = (context: StrategyContext) => Promise<string[]>;
+export declare const HeaderStrategies: {
+    /**
+     * Default strategy: Returns only the headers currently visible in the DOM.
+     * This is fast but won't find virtualized columns off-screen.
+     */
+    visible: ({ config, resolve, root }: StrategyContext) => Promise<string[]>;
+    /**
+     * Scans for headers by finding a scrollable container and setting scrollLeft.
+     */
+    scrollRight: (context: StrategyContext, options?: {
+        limit?: number;
+        selector?: string;
+        scrollAmount?: number;
+    }) => Promise<string[]>;
+    /**
+     * Strategy that clicks into the table to establish focus and then uses the Right Arrow key
+     * to navigate cell-by-cell, collecting headers found along the way.
+     */
+    keyboard: (context: StrategyContext, options?: {
+        limit?: number;
+        maxSilentClicks?: number;
+    }) => Promise<string[]>;
+};

package/dist/strategies/headers.js

@@ -0,0 +1,142 @@
+"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.HeaderStrategies = void 0;
+exports.HeaderStrategies = {
+    /**
+     * Default strategy: Returns only the headers currently visible in the DOM.
+     * This is fast but won't find virtualized columns off-screen.
+     */
+    visible: (_a) => __awaiter(void 0, [_a], void 0, function* ({ config, resolve, root }) {
+        const headerLoc = resolve(config.headerSelector, root);
+        try {
+            // Wait for at least one header to be visible
+            yield headerLoc.first().waitFor({ state: 'visible', timeout: 3000 });
+        }
+        catch (e) {
+            // Ignore hydration/timeout issues, return what we have
+        }
+        const texts = yield headerLoc.allInnerTexts();
+        return texts.map(t => t.trim());
+    }),
+    /**
+     * Scans for headers by finding a scrollable container and setting scrollLeft.
+     */
+    scrollRight: (context, options) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b;
+        const { resolve, config, root, page } = context;
+        const limit = (_a = options === null || options === void 0 ? void 0 : options.limit) !== null && _a !== void 0 ? _a : 20;
+        const scrollAmount = (_b = options === null || options === void 0 ? void 0 : options.scrollAmount) !== null && _b !== void 0 ? _b : 300;
+        const collectedHeaders = new Set();
+        const getVisible = () => __awaiter(void 0, void 0, void 0, function* () {
+            const headerLoc = resolve(config.headerSelector, root);
+            const texts = yield headerLoc.allInnerTexts();
+            return texts.map(t => t.trim());
+        });
+        // Initial capture
+        let currentHeaders = yield getVisible();
+        currentHeaders.forEach(h => collectedHeaders.add(h));
+        // Find scroller using JS for better iframe/shadow support
+        const scrollerHandle = yield root.evaluateHandle((el, selector) => {
+            if (selector && el.matches(selector))
+                return el;
+            const effectiveSelector = selector || '.dvn-scroller';
+            const ancestor = el.closest(effectiveSelector);
+            if (ancestor)
+                return ancestor;
+            return document.querySelector(effectiveSelector);
+        }, options === null || options === void 0 ? void 0 : options.selector);
+        const isScrollerFound = yield scrollerHandle.evaluate(el => !!el);
+        if (isScrollerFound) {
+            yield scrollerHandle.evaluate(el => el.scrollLeft = 0);
+            yield page.waitForTimeout(200);
+            for (let i = 0; i < limit; i++) {
+                const sizeBefore = collectedHeaders.size;
+                yield scrollerHandle.evaluate((el, amount) => el.scrollLeft += amount, scrollAmount);
+                yield page.waitForTimeout(300);
+                const newHeaders = yield getVisible();
+                console.log(`[HeaderStrat:scrollRight] Scrolled ${scrollAmount}, found: ${newHeaders.length} visible.`);
+                newHeaders.forEach(h => collectedHeaders.add(h));
+                if (collectedHeaders.size === sizeBefore) {
+                    yield scrollerHandle.evaluate((el, amount) => el.scrollLeft += amount, scrollAmount);
+                    yield page.waitForTimeout(300);
+                    const retryHeaders = yield getVisible();
+                    retryHeaders.forEach(h => collectedHeaders.add(h));
+                    if (collectedHeaders.size === sizeBefore)
+                        break;
+                }
+            }
+        }
+        else {
+            console.warn("HeaderStrategies.scrollRight: Could not find scroller. Returning visible headers.");
+        }
+        // Scroll back to start
+        yield scrollerHandle.evaluate(el => el.scrollLeft = 0);
+        yield page.waitForTimeout(200);
+        return Array.from(collectedHeaders);
+    }),
+    /**
+     * Strategy that clicks into the table to establish focus and then uses the Right Arrow key
+     * to navigate cell-by-cell, collecting headers found along the way.
+     */
+    keyboard: (context, options) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b;
+        const { resolve, config, root, page } = context;
+        const limit = (_a = options === null || options === void 0 ? void 0 : options.limit) !== null && _a !== void 0 ? _a : 100;
+        const maxSilentClicks = (_b = options === null || options === void 0 ? void 0 : options.maxSilentClicks) !== null && _b !== void 0 ? _b : 10;
+        const collectedHeaders = new Set();
+        const getVisible = () => __awaiter(void 0, void 0, void 0, function* () {
+            const headerLoc = resolve(config.headerSelector, root);
+            const texts = yield headerLoc.allInnerTexts();
+            return texts.map(t => t.trim());
+        });
+        // 1. Initial capture
+        let currentHeaders = yield getVisible();
+        currentHeaders.forEach(h => collectedHeaders.add(h));
+        // 2. Click to focus
+        // Try to find the canvas sibling specifically for Glide, otherwise click root
+        const canvas = root.locator('xpath=ancestor::div').locator('canvas').first();
+        if ((yield canvas.count()) > 0) {
+            // Click lower in the canvas to hit a data cell instead of header
+            // Adjusted to y=60 to target Row 1
+            yield canvas.click({ position: { x: 50, y: 60 }, force: true }).catch(() => { });
+        }
+        else {
+            yield root.click({ position: { x: 10, y: 10 }, force: true }).catch(() => { });
+        }
+        // Reset to home
+        yield page.keyboard.press('Control+Home');
+        yield page.keyboard.press('Home');
+        yield page.waitForTimeout(200);
+        currentHeaders = yield getVisible();
+        currentHeaders.forEach(h => collectedHeaders.add(h));
+        // 3. Navigate right loop
+        let silentCounter = 0;
+        for (let i = 0; i < limit; i++) {
+            const sizeBefore = collectedHeaders.size;
+            yield page.keyboard.press('ArrowRight');
+            yield page.waitForTimeout(100);
+            const newHeaders = yield getVisible();
+            console.log(`[HeaderStrat:keyboard] Step ${i}, found visible: ${newHeaders}`);
+            newHeaders.forEach(h => collectedHeaders.add(h));
+            if (collectedHeaders.size === sizeBefore) {
+                silentCounter++;
+            }
+            else {
+                silentCounter = 0;
+            }
+            if (silentCounter >= maxSilentClicks) {
+                break;
+            }
+        }
+        return Array.from(collectedHeaders);
+    }),
+};

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  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  smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext;\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 interface TableConfig {\n  rowSelector?: Selector;\n  headerSelector?: Selector;\n  cellSelector?: Selector;\n  pagination?: PaginationStrategy;\n  sorting?: SortingStrategy;\n  maxPages?: number;\n  /**\n   * Hook to rename columns dynamically.\n   * * @param args.text - The default innerText of the header.\n   * @param args.index - The column index.\n   * @param args.locator - The specific header cell locator.\n   */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  autoScroll?: boolean;\n  /**\n   * Enable debug mode to log internal state to console.\n   */\n  debug?: boolean;\n  /**\n   * Strategy to reset the table to the initial page.\n   * Called when table.reset() is invoked.\n   */\n  onReset?: (context: TableContext) => Promise<void>;\n}\n\n/**\n * Represents the final, resolved table configuration after default values have been applied.\n * All optional properties from TableConfig are now required, except for `sorting`.\n */\nexport type FinalTableConfig = Required<Omit<TableConfig, 'sorting'>> & {\n  sorting?: SortingStrategy;\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   * Columns not specified here will use auto-detection.\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    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean }\n  ) => SmartRow;\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  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'>;\n";
+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";