@rickcedwhat/playwright-smart-table 6.2.0 → 6.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 **Production-ready table testing for Playwright with smart column-aware locators.**
 
-[![npm version](https://img.shields.io/npm/v/@rickcedwhat/playwright-smart-table.svg)](https://www.npmjs.com/package/@rickcedwhat/playwright-smart-table)
+[![npm version](https://img.shields.io/github/package-json/v/rickcedwhat/playwright-smart-table?label=npm&color=blue&t=2)](https://www.npmjs.com/package/@rickcedwhat/playwright-smart-table)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
@@ -84,7 +84,7 @@ const allActive = await table.findRows({ Status: 'Active' });
 - 📄 **Auto-Pagination** - Search across all pages automatically
 - 🔍 **Column-Aware Access** - Access cells by column name
 - 🛠️ **Debug Mode** - Visual debugging with slow motion and logging
-- 🔌 **Extensible Strategies** - Support any table implementation
+- 🔌 **[Extensible Strategies](docs/concepts/strategies.md)** - Support any table implementation
 - 💪 **Type-Safe** - Full TypeScript support
 - 🚀 **Production-Ready** - Battle-tested in real-world applications
 

package/dist/engine/rowFinder.d.ts

@@ -1,5 +1,5 @@
 import type { Locator, Page } from '@playwright/test';
-import { FinalTableConfig, Selector, SmartRow } from '../types';
+import { FinalTableConfig, Selector, SmartRow, FilterValue } from '../types';
 import { FilterEngine } from '../filterEngine';
 import { TableMapper } from './tableMapper';
 import { SmartRowArray } from '../utils/smartRowArray';
@@ -12,15 +12,16 @@ export declare class RowFinder<T = any> {
     private resolve;
     constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number) => SmartRow<T>);
     private log;
-    findRow(filters: Record<string, string | RegExp | number>, options?: {
+    findRow(filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
     }): Promise<SmartRow<T>>;
-    findRows<R extends {
-        asJSON?: boolean;
-    }>(filters: Partial<T> | Record<string, string | RegExp | number>, options?: {
+    findRows(filtersOrOptions?: (Partial<T> | Record<string, FilterValue>) & ({
         exact?: boolean;
         maxPages?: number;
-    } & R): Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRowArray<T>>;
+    }), legacyOptions?: {
+        exact?: boolean;
+        maxPages?: number;
+    }): Promise<SmartRowArray<T>>;
     private findRowLocator;
 }

package/dist/engine/rowFinder.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RowFinder = void 0;
 const debugUtils_1 = require("../utils/debugUtils");
@@ -42,21 +53,48 @@ class RowFinder {
             return this.makeSmartRow(sentinel, yield this.tableMapper.getMap(), 0);
         });
     }
-    findRows(filters, options) {
+    findRows(filtersOrOptions, 
+    // Deprecated: verify legacy usage pattern support
+    legacyOptions) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Detect argument pattern:
+            // Pattern A: findRows({ Name: 'Alice' }, { maxPages: 5 })
+            // Pattern B: findRows({ maxPages: 5 })  <-- No filters, just options
+            // Pattern C: findRows({ Name: 'Alice' }) <-- Only filters
             var _a, _b;
+            let filters = {};
+            let options = {};
+            if (legacyOptions) {
+                // Pattern A
+                filters = filtersOrOptions;
+                options = legacyOptions;
+            }
+            else {
+                // Pattern B or C
+                // We need to separate unknown keys (filters) from known options (exact, maxPages)
+                // However, filtersOrOptions can be null/undefined
+                if (filtersOrOptions) {
+                    const _c = filtersOrOptions, { exact, maxPages } = _c, rest = __rest(_c, ["exact", "maxPages"]);
+                    options = { exact, maxPages };
+                    filters = rest;
+                }
+            }
             const map = yield this.tableMapper.getMap();
             const allRows = [];
-            const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
+            const effectiveMaxPages = (_b = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
             let pageCount = 0;
             const collectMatches = () => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b;
+                // ... logic ...
                 let rowLocators = this.resolve(this.config.rowSelector, this.rootLocator);
-                rowLocators = this.filterEngine.applyFilters(rowLocators, filters, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page());
+                // Only apply filters if we have them
+                if (Object.keys(filters).length > 0) {
+                    rowLocators = this.filterEngine.applyFilters(rowLocators, filters, map, (_a = options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page());
+                }
                 const currentRows = yield rowLocators.all();
                 const isRowLoading = (_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isRowLoading;
                 for (let i = 0; i < currentRows.length; i++) {
-                    const smartRow = this.makeSmartRow(currentRows[i], map, i);
+                    const smartRow = this.makeSmartRow(currentRows[i], map, allRows.length + i);
                     if (isRowLoading && (yield isRowLoading(smartRow)))
                         continue;
                     allRows.push(smartRow);
@@ -64,31 +102,25 @@ class RowFinder {
             });
             // Scan first page
             yield collectMatches();
-            // Pagination Loop
-            while (pageCount < effectiveMaxPages && this.config.strategies.pagination) {
-                // Check if pagination needed? findRows assumes we want ALL matches across maxPages.
-                // If explicit maxPages is set, we paginate. If global maxPages is 1 (default), we stop.
-                // Wait, loop condition `pageCount < effectiveMaxPages`. If maxPages=1, 0 < 1 is true.
-                // We paginate AFTER first scan.
-                // If maxPages=1, we should NOT paginate.
-                if (effectiveMaxPages <= 1)
-                    break;
+            // Pagination Loop - Corrected logic
+            // We always scan at least 1 page.
+            // If maxPages > 1, and we have a pagination strategy, we try to go next.
+            while (pageCount < effectiveMaxPages - 1 && this.config.strategies.pagination) {
                 const context = {
                     root: this.rootLocator,
                     config: this.config,
                     resolve: this.resolve,
                     page: this.rootLocator.page()
                 };
+                // Check if we should stop? (e.g. if we found enough rows? No, findRows finds ALL)
                 const paginationResult = yield this.config.strategies.pagination(context);
-                const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
+                const didPaginate = yield (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                 if (!didPaginate)
                     break;
                 pageCount++;
+                // Wait for reload logic if needed? Usually pagination handles it.
                 yield collectMatches();
             }
-            if (options === null || options === void 0 ? void 0 : options.asJSON) {
-                return Promise.all(allRows.map(r => r.toJSON()));
-            }
             return (0, smartRowArray_1.createSmartRowArray)(allRows);
         });
     }

package/dist/filterEngine.d.ts

@@ -1,5 +1,5 @@
 import { Locator, Page } from "@playwright/test";
-import { FinalTableConfig } from "./types";
+import { FinalTableConfig, FilterValue } from "./types";
 export declare class FilterEngine {
     private config;
     private resolve;
@@ -7,5 +7,5 @@ export declare class FilterEngine {
     /**
      * Applies filters to a set of rows.
      */
-    applyFilters(baseRows: Locator, filters: Record<string, string | RegExp | number>, map: Map<string, number>, exact: boolean, page: Page): Locator;
+    applyFilters(baseRows: Locator, filters: Record<string, FilterValue>, map: Map<string, number>, exact: boolean, page: Page): Locator;
 }

package/dist/filterEngine.js

@@ -20,7 +20,7 @@ class FilterEngine {
             if (colIndex === undefined) {
                 throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, Array.from(map.keys())));
             }
-            const filterVal = typeof value === 'number' ? String(value) : value;
+            const filterVal = value;
             // Use strategy if provided (For future: configured filter strategies)
             // But for now, we implement the default logic or use custom if we add it to config later
             // Default Filter Logic
@@ -29,9 +29,20 @@ class FilterEngine {
             // filter({ has: ... }) checks if the row *contains* the matching cell.
             // But we need to be specific about WHICH cell.
             // Locator filtering by `has: locator.nth(index)` works if `locator` search is relative to the row.
-            filtered = filtered.filter({
-                has: cellTemplate.nth(colIndex).getByText(filterVal, { exact }),
-            });
+            const targetCell = cellTemplate.nth(colIndex);
+            if (typeof filterVal === 'function') {
+                // Locator-based filter: (cell) => cell.locator(...)
+                filtered = filtered.filter({
+                    has: filterVal(targetCell)
+                });
+            }
+            else {
+                // Text-based filter
+                const textVal = typeof filterVal === 'number' ? String(filterVal) : filterVal;
+                filtered = filtered.filter({
+                    has: targetCell.getByText(textVal, { exact }),
+                });
+            }
         }
         return filtered;
     }

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './useTable';
 export * from './types';
+export * from './plugins';

package/dist/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./useTable"), exports);
 __exportStar(require("./types"), exports);
+__exportStar(require("./plugins"), exports);

package/dist/plugins.d.ts

@@ -16,11 +16,13 @@ export declare const Plugins: {
                 selector?: string;
                 scrollAmount?: number;
             }) => Promise<string[]>;
-            cellNavigation: (context: import("./types").StrategyContext & {
-                column: string;
-                index: number;
-                rowIndex?: number;
-            }) => Promise<void>;
+            navigation: {
+                goUp: (context: import("./types").StrategyContext) => Promise<void>;
+                goDown: (context: import("./types").StrategyContext) => Promise<void>;
+                goLeft: (context: import("./types").StrategyContext) => Promise<void>;
+                goRight: (context: import("./types").StrategyContext) => Promise<void>;
+                goHome: (context: import("./types").StrategyContext) => Promise<void>;
+            };
             getCellLocator: ({ row, columnIndex }: any) => any;
             getActiveCell: ({ page }: any) => Promise<{
                 rowIndex: number;

package/dist/smartRow.d.ts

@@ -4,4 +4,4 @@ import { SmartRow as SmartRowType, FinalTableConfig, TableResult } from './types
  * Factory to create a SmartRow by extending a Playwright Locator.
  * We avoid Class/Proxy to ensure full compatibility with Playwright's expect(locator) matchers.
  */
-export declare const createSmartRow: <T = any>(rowLocator: Locator, map: Map<string, number>, rowIndex: number | undefined, config: FinalTableConfig, rootLocator: Locator, resolve: (item: any, parent: Locator | Page) => Locator, table: TableResult<T> | null) => SmartRowType<T>;
+export declare const createSmartRow: <T = any>(rowLocator: Locator, map: Map<string, number>, rowIndex: number | undefined, config: FinalTableConfig<T>, rootLocator: Locator, resolve: (item: any, parent: Locator | Page) => Locator, table: TableResult<T> | null) => SmartRowType<T>;

package/dist/smartRow.js

@@ -13,6 +13,99 @@ exports.createSmartRow = void 0;
 const fill_1 = require("./strategies/fill");
 const stringUtils_1 = require("./utils/stringUtils");
 const debugUtils_1 = require("./utils/debugUtils");
+/**
+ * Internal helper to navigate to a cell with active cell optimization.
+ * Uses navigation primitives (goUp, goDown, goLeft, goRight, goHome) for orchestration.
+ * Falls back to cellNavigation for backward compatibility.
+ * Returns the target cell locator after navigation.
+ */
+const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function* () {
+    const { config, rootLocator, page, resolve, column, index, rowLocator, rowIndex } = params;
+    // Get active cell if strategy is available
+    let activeCell = null;
+    if (config.strategies.getActiveCell) {
+        activeCell = yield config.strategies.getActiveCell({
+            config,
+            root: rootLocator,
+            page,
+            resolve
+        });
+        // Optimization: Check if we are ALREADY at the target cell
+        if (activeCell && activeCell.rowIndex === rowIndex && activeCell.columnIndex === index) {
+            // Skip navigation - we're already there!
+            return activeCell.locator;
+        }
+    }
+    const context = { config, root: rootLocator, page, resolve };
+    // Use navigation primitives if available
+    if (config.strategies.navigation) {
+        const nav = config.strategies.navigation;
+        if (typeof rowIndex !== 'number') {
+            throw new Error('Row index is required for navigation');
+        }
+        // Determine starting position
+        let startRow = 0;
+        let startCol = 0;
+        if (activeCell && activeCell.rowIndex >= 0 && activeCell.columnIndex >= 0) {
+            // Use current position
+            startRow = activeCell.rowIndex;
+            startCol = activeCell.columnIndex;
+        }
+        else if (nav.goHome) {
+            // Reset to top-left
+            yield nav.goHome(context);
+        }
+        // Calculate movement needed
+        const rowDiff = rowIndex - startRow;
+        const colDiff = index - startCol;
+        // Navigate vertically
+        for (let i = 0; i < Math.abs(rowDiff); i++) {
+            if (rowDiff > 0 && nav.goDown) {
+                yield nav.goDown(context);
+            }
+            else if (rowDiff < 0 && nav.goUp) {
+                yield nav.goUp(context);
+            }
+        }
+        // Navigate horizontally
+        for (let i = 0; i < Math.abs(colDiff); i++) {
+            if (colDiff > 0 && nav.goRight) {
+                yield nav.goRight(context);
+            }
+            else if (colDiff < 0 && nav.goLeft) {
+                yield nav.goLeft(context);
+            }
+        }
+        yield page.waitForTimeout(50);
+    }
+    else if (config.strategies.cellNavigation) {
+        // Fallback to legacy cellNavigation strategy
+        yield config.strategies.cellNavigation({
+            config,
+            root: rootLocator,
+            page,
+            resolve,
+            column,
+            index,
+            rowLocator,
+            rowIndex,
+            activeCell
+        });
+    }
+    // Get the active cell locator after navigation (for virtualized tables)
+    if (config.strategies.getActiveCell) {
+        const updatedActiveCell = yield config.strategies.getActiveCell({
+            config,
+            root: rootLocator,
+            page,
+            resolve
+        });
+        if (updatedActiveCell) {
+            return updatedActiveCell.locator;
+        }
+    }
+    return null;
+});
 /**
  * Factory to create a SmartRow by extending a Playwright Locator.
  * We avoid Class/Proxy to ensure full compatibility with Playwright's expect(locator) matchers.
@@ -39,13 +132,23 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         return resolve(config.cellSelector, rowLocator).nth(idx);
     };
     smart.toJSON = (options) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
         const result = {};
         const page = rootLocator.page();
         for (const [col, idx] of map.entries()) {
             if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(col)) {
                 continue;
             }
-            // Get the cell locator
+            // Check if we have a data mapper for this column
+            const mapper = (_a = config.dataMapper) === null || _a === void 0 ? void 0 : _a[col];
+            if (mapper) {
+                // Use custom mapper
+                // Ensure we have the cell first (same navigation logic)
+                // ... wait, the navigation logic below assumes we need to navigate.
+                // If we have a mapper, we still need the cell locator.
+                // Let's reuse the navigation logic to get targetCell
+            }
+            // --- Navigation Logic Start ---
             const cell = config.strategies.getCellLocator
                 ? config.strategies.getCellLocator({
                     row: rowLocator,
@@ -56,59 +159,34 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 })
                 : resolve(config.cellSelector, rowLocator).nth(idx);
             let targetCell = cell;
-            // Check if cell exists
             const count = yield cell.count();
             if (count === 0) {
-                // Optimization: Check if we are ALREADY at the target cell
-                if (config.strategies.getActiveCell) {
-                    const active = yield config.strategies.getActiveCell({
-                        config,
-                        root: rootLocator,
-                        page,
-                        resolve
-                    });
-                    if (active && active.rowIndex === rowIndex && active.columnIndex === idx) {
-                        if (config.debug)
-                            console.log(`[SmartRow] Already at target cell (r:${active.rowIndex}, c:${active.columnIndex}), skipping navigation.`);
-                        targetCell = active.locator;
-                        // Skip navigation and go to reading text
-                        const text = yield targetCell.innerText();
-                        result[col] = (text || '').trim();
-                        continue;
-                    }
-                }
-                // Cell doesn't exist - navigate to it
-                if (config.debug) {
-                    console.log(`[SmartRow.toJSON] Cell not found for column "${col}" (index ${idx}), navigating...`);
-                }
-                yield config.strategies.cellNavigation({
-                    config: config,
-                    root: rootLocator,
-                    page: page,
-                    resolve: resolve,
+                // Cell not in DOM (virtualized) - navigate to it
+                const navigatedCell = yield _navigateToCell({
+                    config,
+                    rootLocator,
+                    page,
+                    resolve,
                     column: col,
                     index: idx,
-                    rowLocator: rowLocator,
-                    rowIndex: rowIndex
+                    rowLocator,
+                    rowIndex
                 });
-                // Optimization: check if we can get the active cell directly
-                if (config.strategies.getActiveCell) {
-                    const activeCell = yield config.strategies.getActiveCell({
-                        config,
-                        root: rootLocator,
-                        page,
-                        resolve
-                    });
-                    if (activeCell) {
-                        if (config.debug) {
-                            console.log(`[SmartRow.toJSON] switching to active cell locator (r:${activeCell.rowIndex}, c:${activeCell.columnIndex})`);
-                        }
-                        targetCell = activeCell.locator;
-                    }
+                if (navigatedCell) {
+                    targetCell = navigatedCell;
                 }
             }
-            const text = yield targetCell.innerText();
-            result[col] = (text || '').trim();
+            // --- Navigation Logic End ---
+            if (mapper) {
+                // Apply mapper
+                const mappedValue = yield mapper(targetCell);
+                result[col] = mappedValue;
+            }
+            else {
+                // Default string extraction
+                const text = yield targetCell.innerText();
+                result[col] = (text || '').trim();
+            }
         }
         return result;
     });
@@ -121,15 +199,15 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             if (colIdx === undefined) {
                 throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, Array.from(map.keys())));
             }
-            yield config.strategies.cellNavigation({
-                config: config,
-                root: rootLocator,
+            yield _navigateToCell({
+                config,
+                rootLocator,
                 page: rootLocator.page(),
-                resolve: resolve,
+                resolve,
                 column: colName,
                 index: colIdx,
-                rowLocator: rowLocator,
-                rowIndex: rowIndex
+                rowLocator,
+                rowIndex
             });
             const strategy = config.strategies.fill || fill_1.FillStrategies.default;
             (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);

package/dist/strategies/columns.d.ts

@@ -1,13 +1,29 @@
+import type { Locator } from '@playwright/test';
 import { StrategyContext } from '../types';
 /**
+ * Primitive navigation functions that define HOW to move within a table.
+ * The orchestration logic (WHEN to move) lives in _navigateToCell.
+ */
+export interface NavigationPrimitives {
+    goUp?: (context: StrategyContext) => Promise<void>;
+    goDown?: (context: StrategyContext) => Promise<void>;
+    goLeft?: (context: StrategyContext) => Promise<void>;
+    goRight?: (context: StrategyContext) => Promise<void>;
+    goHome?: (context: StrategyContext) => Promise<void>;
+}
+/**
+ * @deprecated Use NavigationPrimitives instead. This will be removed in a future version.
  * Defines the contract for a cell navigation strategy.
- * It is responsible for ensuring a specific CELL is visible/focused (navigates to row + column),
- * typically by scrolling or using keyboard navigation.
  */
 export type CellNavigationStrategy = (context: StrategyContext & {
     column: string;
     index: number;
     rowIndex?: number;
+    activeCell?: {
+        rowIndex: number;
+        columnIndex: number;
+        locator: Locator;
+    } | null;
 }) => Promise<void>;
 export declare const CellNavigationStrategies: {
     /**

package/dist/strategies/glide/columns.d.ts

@@ -1,13 +1,11 @@
 import { StrategyContext } from '../../types';
 /**
- * Strategy that clicks into the table to establish focus and then uses the Right Arrow key
- * to navigate to the target CELL (navigates down to the row, then right to the column).
- *
- * 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.
+ * Primitive navigation functions for Glide Data Grid.
+ * These define HOW to move, not WHEN to move.
+ * The orchestration logic lives in _navigateToCell.
  */
-export declare const keyboardCellNavigation: (context: StrategyContext & {
-    column: string;
-    index: number;
-    rowIndex?: number;
-}) => Promise<void>;
+export declare const glideGoUp: (context: StrategyContext) => Promise<void>;
+export declare const glideGoDown: (context: StrategyContext) => Promise<void>;
+export declare const glideGoLeft: (context: StrategyContext) => Promise<void>;
+export declare const glideGoRight: (context: StrategyContext) => Promise<void>;
+export declare const glideGoHome: (context: StrategyContext) => Promise<void>;

package/dist/strategies/glide/columns.js

@@ -9,35 +9,36 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.keyboardCellNavigation = void 0;
+exports.glideGoHome = exports.glideGoRight = exports.glideGoLeft = exports.glideGoDown = exports.glideGoUp = void 0;
 /**
- * Strategy that clicks into the table to establish focus and then uses the Right Arrow key
- * to navigate to the target CELL (navigates down to the row, then right to the column).
- *
- * 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.
+ * Primitive navigation functions for Glide Data Grid.
+ * These define HOW to move, not WHEN to move.
+ * The orchestration logic lives in _navigateToCell.
  */
-const keyboardCellNavigation = (context) => __awaiter(void 0, void 0, void 0, function* () {
-    const { root, page, index, rowIndex } = context;
-    if (typeof rowIndex !== 'number') {
-        throw new Error('Row index is required for keyboard navigation');
-    }
+const glideGoUp = (context) => __awaiter(void 0, void 0, void 0, function* () {
+    yield context.page.keyboard.press('ArrowUp');
+});
+exports.glideGoUp = glideGoUp;
+const glideGoDown = (context) => __awaiter(void 0, void 0, void 0, function* () {
+    yield context.page.keyboard.press('ArrowDown');
+});
+exports.glideGoDown = glideGoDown;
+const glideGoLeft = (context) => __awaiter(void 0, void 0, void 0, function* () {
+    yield context.page.keyboard.press('ArrowLeft');
+});
+exports.glideGoLeft = glideGoLeft;
+const glideGoRight = (context) => __awaiter(void 0, void 0, void 0, function* () {
+    yield context.page.keyboard.press('ArrowRight');
+});
+exports.glideGoRight = glideGoRight;
+const glideGoHome = (context) => __awaiter(void 0, void 0, void 0, function* () {
+    const { root, page } = context;
     yield root.focus();
     yield page.waitForTimeout(100);
-    // Robust Navigation:
-    // 1. Jump to Top-Left (Reset) - Sequence for Cross-OS (Mac/Windows)
+    // Reset to top-left - Cross-OS sequence (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(150);
-    // 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(50);
 });
-exports.keyboardCellNavigation = keyboardCellNavigation;
+exports.glideGoHome = glideGoHome;

package/dist/strategies/glide.d.ts

@@ -15,11 +15,13 @@ export declare const GlideStrategies: {
         selector?: string;
         scrollAmount?: number;
     }) => Promise<string[]>;
-    cellNavigation: (context: import("../types").StrategyContext & {
-        column: string;
-        index: number;
-        rowIndex?: number;
-    }) => Promise<void>;
+    navigation: {
+        goUp: (context: import("../types").StrategyContext) => Promise<void>;
+        goDown: (context: import("../types").StrategyContext) => Promise<void>;
+        goLeft: (context: import("../types").StrategyContext) => Promise<void>;
+        goRight: (context: import("../types").StrategyContext) => Promise<void>;
+        goHome: (context: import("../types").StrategyContext) => Promise<void>;
+    };
     getCellLocator: ({ row, columnIndex }: any) => any;
     getActiveCell: ({ page }: any) => Promise<{
         rowIndex: number;

package/dist/strategies/glide.js

@@ -92,7 +92,13 @@ exports.GlideStrategies = {
     fill: exports.glideFillStrategy,
     pagination: exports.glidePaginationStrategy,
     header: headers_1.scrollRightHeader,
-    cellNavigation: columns_1.keyboardCellNavigation,
+    navigation: {
+        goUp: columns_1.glideGoUp,
+        goDown: columns_1.glideGoDown,
+        goLeft: columns_1.glideGoLeft,
+        goRight: columns_1.glideGoRight,
+        goHome: columns_1.glideGoHome
+    },
     getCellLocator: exports.glideGetCellLocator,
     getActiveCell: exports.glideGetActiveCell
 };

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 = "\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  isHeaderLoading?: (context: TableContext) => 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>[] : SmartRowArray>;\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: SmartRowArray, allData: any[] }) => void | Promise<void>;\n      afterLast?: (context: { index: number, rows: SmartRowArray, 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";
+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 * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => 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<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\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, NavigationPrimitives } 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: FilterValue };\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  isHeaderLoading?: (context: TableContext) => 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  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */\n  navigation?: NavigationPrimitives;\n  /** @deprecated Use navigation primitives instead. 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 */\n/**\n * Configuration options for useTable.\n */\nexport interface TableConfig<T = any> {\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   * Custom data mappers for specific columns.\n   * Allows extracting complex data types (boolean, number) instead of just string.\n   */\n  dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;\n}\n\nexport interface FinalTableConfigLike<T = any> extends TableConfig<T> {\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// Alias for backward compatibility if needed, or update usages\nexport type FinalTableConfig<T = any> = FinalTableConfigLike<T>;\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, FilterValue>,\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, FilterValue>,\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 and max pages\n   */\n  findRows: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\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: SmartRowArray, allData: any[] }) => void | Promise<void>;\n      afterLast?: (context: { index: number, rows: SmartRowArray, 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";

package/dist/typeContext.js

@@ -18,6 +18,19 @@ exports.TYPE_CONTEXT = `
  */
 export type Selector = string | ((root: Locator | Page) => Locator);
 
+/**
+ * Value used to filter rows.
+ * - string/number/RegExp: filter by text content of the cell.
+ * - function: filter by custom locator logic within the cell.
+ * @example
+ * // Text filter
+ * { Name: 'John' }
+ * 
+ * // Custom locator filter (e.g. checkbox is checked)
+ * { Status: (cell) => cell.locator('input:checked') }
+ */
+export type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);
+
 /**
  * Function to get a cell locator given row, column info.
  * Replaces the old cellResolver.
@@ -158,9 +171,9 @@ export type DebugConfig = {
   logLevel?: 'verbose' | 'info' | 'error' | 'none';
 };
 
-export interface TableContext {
+export interface TableContext<T = any> {
   root: Locator;
-  config: FinalTableConfig;
+  config: FinalTableConfig<T>;
   page: Page;
   resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
@@ -191,7 +204,7 @@ export type FillStrategy = (options: {
 }) => Promise<void>;
 
 export type { HeaderStrategy } from './strategies/headers';
-export type { CellNavigationStrategy } from './strategies/columns';
+export type { CellNavigationStrategy, NavigationPrimitives } from './strategies/columns';
 
 /**
  * Strategy to resolve column names (string or regex) to their index.
@@ -204,7 +217,7 @@ export type { ColumnResolutionStrategy } from './strategies/resolution';
 export interface FilterStrategy {
   apply(options: {
     rows: Locator;
-    filter: { column: string, value: string | RegExp | number };
+    filter: { column: string, value: FilterValue };
     colIndex: number;
     tableContext: TableContext;
   }): Locator;
@@ -225,7 +238,9 @@ export interface LoadingStrategy {
 export interface TableStrategies {
   /** Strategy for discovering/scanning headers */
   header?: HeaderStrategy;
-  /** Strategy for navigating to specific cells (row + column) */
+  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */
+  navigation?: NavigationPrimitives;
+  /** @deprecated Use navigation primitives instead. Strategy for navigating to specific cells (row + column) */
   cellNavigation?: CellNavigationStrategy;
   /** Strategy for filling form inputs */
   fill?: FillStrategy;
@@ -252,7 +267,10 @@ export interface TableStrategies {
 /**
  * Configuration options for useTable.
  */
-export interface TableConfig {
+/**
+ * Configuration options for useTable.
+ */
+export interface TableConfig<T = any> {
   /** Selector for the table headers */
   headerSelector?: string;
   /** Selector for the table rows */
@@ -271,9 +289,14 @@ export interface TableConfig {
   onReset?: (context: TableContext) => Promise<void>;
   /** All interaction strategies */
   strategies?: TableStrategies;
+  /**
+   * Custom data mappers for specific columns.
+   * Allows extracting complex data types (boolean, number) instead of just string.
+   */
+  dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;
 }
 
-export interface FinalTableConfig extends TableConfig {
+export interface FinalTableConfigLike<T = any> extends TableConfig<T> {
   headerSelector: string;
   rowSelector: string;
   cellSelector: string;
@@ -284,6 +307,8 @@ export interface FinalTableConfig extends TableConfig {
   onReset: (context: TableContext) => Promise<void>;
   strategies: TableStrategies;
 }
+// Alias for backward compatibility if needed, or update usages
+export type FinalTableConfig<T = any> = FinalTableConfigLike<T>;
 
 
 export interface FillOptions {
@@ -332,7 +357,7 @@ export interface TableResult<T = any> {
    * Throws error if table is not initialized.
    */
   getRow: (
-    filters: Record<string, string | RegExp | number>,
+    filters: Record<string, FilterValue>,
     options?: { exact?: boolean }
   ) => SmartRow;
 
@@ -354,7 +379,7 @@ export interface TableResult<T = any> {
    * @param options - Search options including exact match and max pages
    */
   findRow: (
-    filters: Record<string, string | RegExp | number>,
+    filters: Record<string, FilterValue>,
     options?: { exact?: boolean, maxPages?: number }
   ) => Promise<SmartRow>;
 
@@ -362,12 +387,12 @@ export interface TableResult<T = any> {
    * 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
+   * @param options - Search options including exact match and max pages
    */
-  findRows: <R extends { asJSON?: boolean }>(
-    filters: Record<string, string | RegExp | number>,
-    options?: { exact?: boolean, maxPages?: number } & R
-  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRowArray>;
+  findRows: (
+    filters: Record<string, FilterValue>,
+    options?: { exact?: boolean, maxPages?: number }
+  ) => Promise<SmartRowArray<T>>;
 
   /**
    * Navigates to a specific column using the configured CellNavigationStrategy.

package/dist/types.d.ts

@@ -10,6 +10,18 @@ import type { SmartRowArray } from './utils/smartRowArray';
  * rowSelector: (root) => root.locator('[role="row"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator);
+/**
+ * Value used to filter rows.
+ * - string/number/RegExp: filter by text content of the cell.
+ * - function: filter by custom locator logic within the cell.
+ * @example
+ * // Text filter
+ * { Name: 'John' }
+ *
+ * // Custom locator filter (e.g. checkbox is checked)
+ * { Status: (cell) => cell.locator('input:checked') }
+ */
+export type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);
 /**
  * Function to get a cell locator given row, column info.
  * Replaces the old cellResolver.
@@ -143,9 +155,9 @@ export type DebugConfig = {
      */
     logLevel?: 'verbose' | 'info' | 'error' | 'none';
 };
-export interface TableContext {
+export interface TableContext<T = any> {
     root: Locator;
-    config: FinalTableConfig;
+    config: FinalTableConfig<T>;
     page: Page;
     resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
@@ -171,9 +183,9 @@ export type FillStrategy = (options: {
     fillOptions?: FillOptions;
 }) => Promise<void>;
 export type { HeaderStrategy } from './strategies/headers';
-export type { CellNavigationStrategy } from './strategies/columns';
+export type { CellNavigationStrategy, NavigationPrimitives } from './strategies/columns';
 import { HeaderStrategy } from './strategies/headers';
-import { CellNavigationStrategy } from './strategies/columns';
+import { CellNavigationStrategy, NavigationPrimitives } from './strategies/columns';
 /**
  * Strategy to resolve column names (string or regex) to their index.
  */
@@ -186,7 +198,7 @@ export interface FilterStrategy {
         rows: Locator;
         filter: {
             column: string;
-            value: string | RegExp | number;
+            value: FilterValue;
         };
         colIndex: number;
         tableContext: TableContext;
@@ -206,7 +218,9 @@ export interface LoadingStrategy {
 export interface TableStrategies {
     /** Strategy for discovering/scanning headers */
     header?: HeaderStrategy;
-    /** Strategy for navigating to specific cells (row + column) */
+    /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */
+    navigation?: NavigationPrimitives;
+    /** @deprecated Use navigation primitives instead. Strategy for navigating to specific cells (row + column) */
     cellNavigation?: CellNavigationStrategy;
     /** Strategy for filling form inputs */
     fill?: FillStrategy;
@@ -239,7 +253,10 @@ export interface TableStrategies {
 /**
  * Configuration options for useTable.
  */
-export interface TableConfig {
+/**
+ * Configuration options for useTable.
+ */
+export interface TableConfig<T = any> {
     /** Selector for the table headers */
     headerSelector?: string;
     /** Selector for the table rows */
@@ -263,8 +280,13 @@ export interface TableConfig {
     onReset?: (context: TableContext) => Promise<void>;
     /** All interaction strategies */
     strategies?: TableStrategies;
+    /**
+     * Custom data mappers for specific columns.
+     * Allows extracting complex data types (boolean, number) instead of just string.
+     */
+    dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;
 }
-export interface FinalTableConfig extends TableConfig {
+export interface FinalTableConfigLike<T = any> extends TableConfig<T> {
     headerSelector: string;
     rowSelector: string;
     cellSelector: string;
@@ -280,6 +302,7 @@ export interface FinalTableConfig extends TableConfig {
     onReset: (context: TableContext) => Promise<void>;
     strategies: TableStrategies;
 }
+export type FinalTableConfig<T = any> = FinalTableConfigLike<T>;
 export interface FillOptions {
     /**
      * Custom input mappers for specific columns.
@@ -322,7 +345,7 @@ export interface TableResult<T = any> {
      * Finds a row by filters on the current page only. Returns immediately (sync).
      * Throws error if table is not initialized.
      */
-    getRow: (filters: Record<string, string | RegExp | number>, options?: {
+    getRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
     }) => SmartRow;
     /**
@@ -340,7 +363,7 @@ export interface TableResult<T = any> {
      * @param filters - The filter criteria to match
      * @param options - Search options including exact match and max pages
      */
-    findRow: (filters: Record<string, string | RegExp | number>, options?: {
+    findRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
     }) => Promise<SmartRow>;
@@ -348,14 +371,12 @@ export interface TableResult<T = any> {
      * 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
+     * @param options - Search options including exact match and max pages
      */
-    findRows: <R extends {
-        asJSON?: boolean;
-    }>(filters: Record<string, string | RegExp | number>, options?: {
+    findRows: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
-    } & R) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRowArray>;
+    }) => Promise<SmartRowArray<T>>;
     /**
      * Navigates to a specific column using the configured CellNavigationStrategy.
      */

package/dist/useTable.d.ts

@@ -8,7 +8,7 @@ import { Strategies } from './strategies';
 /**
  * Main hook to interact with a table.
  */
-export declare const useTable: <T = any>(rootLocator: Locator, configOptions?: TableConfig) => TableResult<T>;
+export declare const useTable: <T = any>(rootLocator: Locator, configOptions?: TableConfig<T>) => TableResult<T>;
 export declare const PaginationStrategies: {
     clickNext: (nextButtonSelector: Selector, options?: {
         stabilization?: import("./strategies/stabilization").StabilizationStrategy;

package/dist/useTable.js

@@ -225,10 +225,12 @@ const useTable = (rootLocator, configOptions = {}) => {
             return _makeSmart(rowLocator, map, index);
         },
         findRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+            // @ts-ignore
             return rowFinder.findRow(filters, options);
         }),
         getRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
             console.warn('DEPRECATED: table.getRows() is deprecated and will be removed in a future version. Use table.findRows() instead.');
+            // @ts-ignore
             return rowFinder.findRows((options === null || options === void 0 ? void 0 : options.filter) || {}, Object.assign(Object.assign({}, options), { maxPages: 1 }));
         }),
         findRows: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.2.0",
+  "version": "6.3.1",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",