@rickcedwhat/playwright-smart-table 2.1.3 → 2.3.0

package/dist/strategies/sorting.js

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

package/dist/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\nexport interface TableContext {\n  root: Locator;\n  config: Required<TableConfig>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (Best for Cloud/QA Wolf to get clean text).\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  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 first page.\n   * Called when table.reset() is invoked.\n   */\n  onReset?: (context: TableContext) => Promise<void>;\n}\n\nexport interface TableResult {\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  getByRow: <T extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean, maxPages?: number } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string> : 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";
+export declare const TYPE_CONTEXT = "\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\nexport type SmartRow = Omit<Locator, 'fill'> & {\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\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 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 first 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  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  getByRow: <T extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean, maxPages?: number } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string> : 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";

package/dist/typeContext.js

@@ -9,14 +9,42 @@ exports.TYPE_CONTEXT = void 0;
 exports.TYPE_CONTEXT = `
 export type Selector = string | ((root: Locator | Page) => Locator);
 
-export type SmartRow = Locator & {
+export type SmartRow = Omit<Locator, 'fill'> & {
   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>;
 };
 
+export type StrategyContext = TableContext;
+
+/**
+ * Defines the contract for a sorting strategy.
+ */
+export interface SortingStrategy {
+  /**
+   * Performs the sort action on a column.
+   */
+  doSort(options: {
+    columnName: string;
+    direction: 'asc' | 'desc';
+    context: StrategyContext;
+  }): Promise<void>;
+
+  /**
+   * Retrieves the current sort state of a column.
+   */
+  getSortState(options: {
+    columnName: string;
+    context: StrategyContext;
+  }): Promise<'asc' | 'desc' | 'none'>;
+}
+
 export interface TableContext {
   root: Locator;
-  config: Required<TableConfig>;
+  config: FinalTableConfig;
   page: Page;
   resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
@@ -26,7 +54,7 @@ export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
 export interface PromptOptions {
   /**
    * Output Strategy:
-   * - 'error': Throws an error with the prompt (Best for Cloud/QA Wolf to get clean text).
+   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
    * - 'console': Standard console logs (Default).
    */
   output?: 'console' | 'error';
@@ -38,6 +66,7 @@ export interface TableConfig {
   headerSelector?: Selector;
   cellSelector?: Selector;
   pagination?: PaginationStrategy;
+  sorting?: SortingStrategy;
   maxPages?: number;
   /**
    * Hook to rename columns dynamically.
@@ -58,6 +87,23 @@ export interface TableConfig {
   onReset?: (context: TableContext) => Promise<void>;
 }
 
+/**
+ * Represents the final, resolved table configuration after default values have been applied.
+ * All optional properties from TableConfig are now required, except for \`sorting\`.
+ */
+export type FinalTableConfig = Required<Omit<TableConfig, 'sorting'>> & {
+  sorting?: SortingStrategy;
+};
+
+export interface FillOptions {
+  /**
+   * Custom input mappers for specific columns.
+   * Maps column names to functions that return the input locator for that cell.
+   * Columns not specified here will use auto-detection.
+   */
+  inputMappers?: Record<string, (cell: Locator) => Locator>;
+}
+
 export interface TableResult {
   getHeaders: () => Promise<string[]>;
   getHeaderCell: (columnName: string) => Promise<Locator>;
@@ -83,5 +129,23 @@ export interface TableResult {
    * Scans a specific column across all pages and returns the values.
    */
   getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;
+
+  /**
+   * Provides access to sorting actions and assertions.
+   */
+  sorting: {
+    /**
+     * Applies the configured sorting strategy to the specified column.
+     * @param columnName The name of the column to sort.
+     * @param direction The direction to sort ('asc' or 'desc').
+     */
+    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;
+    /**
+     * Gets the current sort state of a column using the configured sorting strategy.
+     * @param columnName The name of the column to check.
+     * @returns A promise that resolves to 'asc', 'desc', or 'none'.
+     */
+    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
+  };
 }
 `;

package/dist/types.d.ts

@@ -1,12 +1,37 @@
 import type { Locator, Page } from '@playwright/test';
 export type Selector = string | ((root: Locator | Page) => Locator);
-export type SmartRow = Locator & {
+export type SmartRow = Omit<Locator, 'fill'> & {
     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>;
 };
+export type StrategyContext = TableContext;
+/**
+ * Defines the contract for a sorting strategy.
+ */
+export interface SortingStrategy {
+    /**
+     * Performs the sort action on a column.
+     */
+    doSort(options: {
+        columnName: string;
+        direction: 'asc' | 'desc';
+        context: StrategyContext;
+    }): Promise<void>;
+    /**
+     * Retrieves the current sort state of a column.
+     */
+    getSortState(options: {
+        columnName: string;
+        context: StrategyContext;
+    }): Promise<'asc' | 'desc' | 'none'>;
+}
 export interface TableContext {
     root: Locator;
-    config: Required<TableConfig>;
+    config: FinalTableConfig;
     page: Page;
     resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
@@ -14,7 +39,7 @@ export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
 export interface PromptOptions {
     /**
      * Output Strategy:
-     * - 'error': Throws an error with the prompt (Best for Cloud/QA Wolf to get clean text).
+     * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
      * - 'console': Standard console logs (Default).
      */
     output?: 'console' | 'error';
@@ -25,6 +50,7 @@ export interface TableConfig {
     headerSelector?: Selector;
     cellSelector?: Selector;
     pagination?: PaginationStrategy;
+    sorting?: SortingStrategy;
     maxPages?: number;
     /**
      * Hook to rename columns dynamically.
@@ -48,6 +74,21 @@ export interface TableConfig {
      */
     onReset?: (context: TableContext) => Promise<void>;
 }
+/**
+ * Represents the final, resolved table configuration after default values have been applied.
+ * All optional properties from TableConfig are now required, except for `sorting`.
+ */
+export type FinalTableConfig = Required<Omit<TableConfig, 'sorting'>> & {
+    sorting?: SortingStrategy;
+};
+export interface FillOptions {
+    /**
+     * Custom input mappers for specific columns.
+     * Maps column names to functions that return the input locator for that cell.
+     * Columns not specified here will use auto-detection.
+     */
+    inputMappers?: Record<string, (cell: Locator) => Locator>;
+}
 export interface TableResult {
     getHeaders: () => Promise<string[]>;
     getHeaderCell: (columnName: string) => Promise<Locator>;
@@ -76,4 +117,21 @@ export interface TableResult {
         mapper?: (cell: Locator) => Promise<V> | V;
         maxPages?: number;
     }) => Promise<V[]>;
+    /**
+     * Provides access to sorting actions and assertions.
+     */
+    sorting: {
+        /**
+         * Applies the configured sorting strategy to the specified column.
+         * @param columnName The name of the column to sort.
+         * @param direction The direction to sort ('asc' or 'desc').
+         */
+        apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;
+        /**
+         * Gets the current sort state of a column using the configured sorting strategy.
+         * @param columnName The name of the column to check.
+         * @returns A promise that resolves to 'asc', 'desc', or 'none'.
+         */
+        getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
+    };
 }

package/dist/useTable.d.ts

@@ -1,3 +1,39 @@
 import type { Locator } from '@playwright/test';
-import { TableConfig, TableResult } from './types';
+import { TableConfig, TableContext, TableResult } from './types';
+/**
+ * A collection of pre-built pagination strategies.
+ */
+export declare const PaginationStrategies: {
+    /**
+     * Clicks a "Next" button.
+     * @param selector - The CSS selector for the "Next" button.
+     */
+    NextButton: (selector: string) => ((context: TableContext) => Promise<boolean>);
+    /**
+     * Clicks numbered page links.
+     * @param selector - The CSS selector for the page number links.
+     */
+    NumberedPages: (selector: string) => ((context: TableContext) => Promise<boolean>);
+};
+/**
+ * @deprecated Use `PaginationStrategies` instead. This alias will be removed in a future major version.
+ */
+export declare const TableStrategies: {
+    /**
+     * Clicks a "Next" button.
+     * @param selector - The CSS selector for the "Next" button.
+     */
+    NextButton: (selector: string) => ((context: TableContext) => Promise<boolean>);
+    /**
+     * Clicks numbered page links.
+     * @param selector - The CSS selector for the page number links.
+     */
+    NumberedPages: (selector: string) => ((context: TableContext) => Promise<boolean>);
+};
+/**
+ * A collection of pre-built sorting strategies.
+ */
+export declare const SortingStrategies: {
+    AriaSort: () => import("./types").SortingStrategy;
+};
 export declare const useTable: (rootLocator: Locator, configOptions?: TableConfig) => TableResult;

package/dist/useTable.js

@@ -9,8 +9,52 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useTable = void 0;
+exports.useTable = exports.SortingStrategies = exports.TableStrategies = exports.PaginationStrategies = void 0;
 const typeContext_1 = require("./typeContext");
+const sorting_1 = require("./strategies/sorting");
+/**
+ * A collection of pre-built pagination strategies.
+ */
+exports.PaginationStrategies = {
+    /**
+     * Clicks a "Next" button.
+     * @param selector - The CSS selector for the "Next" button.
+     */
+    NextButton: (selector) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root }) {
+            const nextButton = root.locator(selector);
+            if ((yield nextButton.isVisible()) && (yield nextButton.isEnabled())) {
+                yield nextButton.click();
+                return true;
+            }
+            return false;
+        });
+    },
+    /**
+     * Clicks numbered page links.
+     * @param selector - The CSS selector for the page number links.
+     */
+    NumberedPages: (selector) => {
+        let currentPage = 1;
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root }) {
+            currentPage++;
+            const pageLink = root.locator(selector).filter({ hasText: String(currentPage) });
+            if (yield pageLink.isVisible()) {
+                yield pageLink.click();
+                return true;
+            }
+            return false;
+        });
+    },
+};
+/**
+ * @deprecated Use `PaginationStrategies` instead. This alias will be removed in a future major version.
+ */
+exports.TableStrategies = exports.PaginationStrategies;
+/**
+ * A collection of pre-built sorting strategies.
+ */
+exports.SortingStrategies = sorting_1.SortingStrategies;
 const useTable = (rootLocator, configOptions = {}) => {
     const config = Object.assign({ rowSelector: "tbody tr", headerSelector: "th", cellSelector: "td", pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }), maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { console.warn("⚠️ .reset() called but no 'onReset' strategy defined in config."); }) }, configOptions);
     const resolve = (item, parent) => {
@@ -27,6 +71,30 @@ const useTable = (rootLocator, configOptions = {}) => {
         if (config.debug)
             console.log(`🔎 [SmartTable Debug] ${msg}`);
     };
+    const _suggestColumnName = (colName, availableColumns) => {
+        // Simple fuzzy matching - find columns with similar names
+        const lowerCol = colName.toLowerCase();
+        const suggestions = availableColumns.filter(col => col.toLowerCase().includes(lowerCol) ||
+            lowerCol.includes(col.toLowerCase()) ||
+            col.toLowerCase().replace(/\s+/g, '') === lowerCol.replace(/\s+/g, ''));
+        if (suggestions.length > 0 && suggestions[0] !== colName) {
+            return `. Did you mean "${suggestions[0]}"?`;
+        }
+        // Show similar column names (first 3)
+        if (availableColumns.length > 0 && availableColumns.length <= 10) {
+            return `. Available columns: ${availableColumns.map(c => `"${c}"`).join(', ')}`;
+        }
+        else if (availableColumns.length > 0) {
+            return `. Available columns (first 5): ${availableColumns.slice(0, 5).map(c => `"${c}"`).join(', ')}, ...`;
+        }
+        return '.';
+    };
+    const _createColumnError = (colName, map, context) => {
+        const availableColumns = Array.from(map.keys());
+        const suggestion = _suggestColumnName(colName, availableColumns);
+        const contextMsg = context ? ` (${context})` : '';
+        return new Error(`Column "${colName}" not found${contextMsg}${suggestion}`);
+    };
     const _getMap = () => __awaiter(void 0, void 0, void 0, function* () {
         if (_headerMap)
             return _headerMap;
@@ -65,8 +133,11 @@ const useTable = (rootLocator, configOptions = {}) => {
         const smart = rowLocator;
         smart.getCell = (colName) => {
             const idx = map.get(colName);
-            if (idx === undefined)
-                throw new Error(`Column '${colName}' not found.`);
+            if (idx === undefined) {
+                const availableColumns = Array.from(map.keys());
+                const suggestion = _suggestColumnName(colName, availableColumns);
+                throw new Error(`Column "${colName}" not found${suggestion}`);
+            }
             if (typeof config.cellSelector === 'string') {
                 return rowLocator.locator(config.cellSelector).nth(idx);
             }
@@ -85,6 +156,92 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return result;
         });
+        smart.fill = (data, fillOptions) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            logDebug(`Filling row with data: ${JSON.stringify(data)}`);
+            // Fill each column
+            for (const [colName, value] of Object.entries(data)) {
+                const colIdx = map.get(colName);
+                if (colIdx === undefined) {
+                    throw _createColumnError(colName, map, 'in fill data');
+                }
+                const cell = smart.getCell(colName);
+                // Use custom input mapper for this column if provided, otherwise auto-detect
+                let inputLocator;
+                if ((_a = fillOptions === null || fillOptions === void 0 ? void 0 : fillOptions.inputMappers) === null || _a === void 0 ? void 0 : _a[colName]) {
+                    inputLocator = fillOptions.inputMappers[colName](cell);
+                }
+                else {
+                    // Auto-detect input type
+                    // Try different input types in order of commonality
+                    // 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;
+                    }
+                    // Warn if multiple inputs found (ambiguous)
+                    const totalInputs = textInputCount + selectCount + checkboxCount + contentEditableCount;
+                    if (totalInputs > 1 && config.debug) {
+                        logDebug(`⚠️ Multiple inputs found in cell "${colName}" (${totalInputs} total). Using first match. Consider using inputMapper option for explicit control.`);
+                    }
+                }
+                // 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);
+                logDebug(`Filling "${colName}" 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));
+                }
+            }
+            logDebug('Fill operation completed');
+        });
         return smart;
     };
     const _applyFilters = (baseRows, filters, map, exact) => {
@@ -92,8 +249,9 @@ const useTable = (rootLocator, configOptions = {}) => {
         const page = rootLocator.page();
         for (const [colName, value] of Object.entries(filters)) {
             const colIndex = map.get(colName);
-            if (colIndex === undefined)
-                throw new Error(`Column '${colName}' not found.`);
+            if (colIndex === undefined) {
+                throw _createColumnError(colName, map, 'in filter');
+            }
             const filterVal = typeof value === 'number' ? String(value) : value;
             const cellTemplate = resolve(config.cellSelector, page);
             filtered = filtered.filter({
@@ -113,8 +271,26 @@ const useTable = (rootLocator, configOptions = {}) => {
             const matchedRows = _applyFilters(allRows, filters, map, options.exact || false);
             const count = yield matchedRows.count();
             logDebug(`Page ${currentPage}: Found ${count} matches.`);
-            if (count > 1)
-                throw new Error(`Strict Mode Violation: Found ${count} rows matching ${JSON.stringify(filters)}.`);
+            if (count > 1) {
+                // Try to get sample row data to help user identify the issue
+                const sampleData = [];
+                try {
+                    const firstFewRows = yield matchedRows.all();
+                    const sampleCount = Math.min(firstFewRows.length, 3);
+                    for (let i = 0; i < sampleCount; i++) {
+                        const rowData = yield _makeSmart(firstFewRows[i], map).toJSON();
+                        sampleData.push(JSON.stringify(rowData));
+                    }
+                }
+                catch (e) {
+                    // If we can't extract sample data, that's okay - continue without it
+                }
+                const sampleMsg = sampleData.length > 0
+                    ? `\nSample matching rows:\n${sampleData.map((d, i) => `  ${i + 1}. ${d}`).join('\n')}`
+                    : '';
+                throw new Error(`Strict Mode Violation: Found ${count} rows matching ${JSON.stringify(filters)} on page ${currentPage}. ` +
+                    `Expected exactly one match. Try adding more filters to make your query unique.${sampleMsg}`);
+            }
             if (count === 1)
                 return matchedRows.first();
             if (currentPage < effectiveMaxPages) {
@@ -181,13 +357,41 @@ const useTable = (rootLocator, configOptions = {}) => {
             return clone.outerHTML;
         });
     });
+    const sortingNamespace = {
+        apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
+            if (!config.sorting) {
+                throw new Error('No sorting strategy has been configured. Please add a `sorting` strategy to your useTable config.');
+            }
+            logDebug(`Applying sort for column "${columnName}" (${direction})`);
+            const context = {
+                root: rootLocator,
+                config: config,
+                page: rootLocator.page(),
+                resolve: resolve
+            };
+            yield config.sorting.doSort({ columnName, direction, context });
+        }),
+        getState: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
+            if (!config.sorting) {
+                throw new Error('No sorting strategy has been configured. Please add a `sorting` strategy to your useTable config.');
+            }
+            logDebug(`Getting sort state for column "${columnName}"`);
+            const context = {
+                root: rootLocator,
+                config: config,
+                page: rootLocator.page(),
+                resolve: resolve
+            };
+            return config.sorting.getSortState({ columnName, context });
+        })
+    };
     return {
         getHeaders: () => __awaiter(void 0, void 0, void 0, function* () { return Array.from((yield _getMap()).keys()); }),
         getHeaderCell: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
             const map = yield _getMap();
             const idx = map.get(columnName);
             if (idx === undefined)
-                throw new Error(`Column '${columnName}' not found.`);
+                throw _createColumnError(columnName, map, 'header cell');
             return resolve(config.headerSelector, rootLocator).nth(idx);
         }),
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
@@ -208,7 +412,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             const map = yield _getMap();
             const colIdx = map.get(column);
             if (colIdx === undefined)
-                throw new Error(`Column '${column}' not found.`);
+                throw _createColumnError(column, map);
             const mapper = (_a = options === null || options === void 0 ? void 0 : options.mapper) !== null && _a !== void 0 ? _a : ((c) => c.innerText());
             const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages;
             let currentPage = 1;
@@ -272,6 +476,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             const content = `\n==================================================\n🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖\n==================================================\nI need a custom Pagination Strategy for 'playwright-smart-table'.\nContainer HTML:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n`;
             yield _handlePrompt('Smart Table Strategy', content, options);
         }),
+        sorting: sortingNamespace,
     };
 };
 exports.useTable = useTable;

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+import { Page } from '@playwright/test';
+/**
+ * Internal helper to wait for a condition to be met.
+ * Replaces the dependency on 'expect(...).toPass()' to ensure compatibility
+ * with environments where 'expect' is not globally available.
+ */
+export declare const waitForCondition: (predicate: () => Promise<boolean>, timeout: number, page: Page) => Promise<boolean>;