@rickcedwhat/playwright-smart-table 2.2.0 → 2.3.0

package/README.md

@@ -480,7 +480,7 @@ export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
 ```typescript
 export interface TableContext {
   root: Locator;
-  config: Required<TableConfig>;
+  config: FinalTableConfig;
   page: Page;
   resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
@@ -513,7 +513,7 @@ await table.generateStrategyPrompt({ output: 'console' });
 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';
@@ -563,6 +563,7 @@ export interface TableConfig {
   headerSelector?: Selector;
   cellSelector?: Selector;
   pagination?: PaginationStrategy;
+  sorting?: SortingStrategy;
   maxPages?: number;
   /**
    * Hook to rename columns dynamically.

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/strategies/index.d.ts

@@ -1,15 +1,2 @@
-import { PaginationStrategy, Selector } from '../types';
-export declare const TableStrategies: {
-    /**
-     * Strategy: Clicks a "Next" button and waits for the first row of data to change.
-     */
-    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
-    /**
-     * Strategy: Clicks a "Load More" button and waits for the row count to increase.
-     */
-    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
-    /**
-     * Strategy: Scrolls to the bottom and waits for more rows to appear.
-     */
-    infiniteScroll: (timeout?: number) => PaginationStrategy;
-};
+export * from './pagination';
+export * from './sorting';

package/dist/strategies/index.js

@@ -1,112 +1,19 @@
 "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.TableStrategies = void 0;
-/**
- * Internal helper to wait for a condition to be met.
- * Replaces the dependency on 'expect(...).toPass()' to ensure compatibility
- * with environments like QA Wolf where 'expect' is not globally available.
- */
-const waitForCondition = (predicate, timeout, page // Context page for pauses
-) => __awaiter(void 0, void 0, void 0, function* () {
-    const startTime = Date.now();
-    while (Date.now() - startTime < timeout) {
-        if (yield predicate()) {
-            return true;
-        }
-        // Wait 100ms before next check (Standard Polling)
-        yield page.waitForTimeout(100).catch(() => new Promise(r => setTimeout(r, 100)));
-    }
-    return false;
-});
-exports.TableStrategies = {
-    /**
-     * Strategy: Clicks a "Next" button and waits for the first row of data to change.
-     */
-    clickNext: (nextButtonSelector, timeout = 5000) => {
-        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
-            const nextBtn = resolve(nextButtonSelector, root).first();
-            // Debug log (can be verbose, maybe useful for debugging only)
-            // console.log(`[Strategy: clickNext] Checking button...`);
-            // Check if button exists/enabled before clicking.
-            // We do NOT wait here because if the button isn't visible/enabled, 
-            // we assume we reached the last page.
-            if (!(yield nextBtn.isVisible())) {
-                console.log(`[Strategy: clickNext] Button not visible. Stopping pagination.`);
-                return false;
-            }
-            if (!(yield nextBtn.isEnabled())) {
-                console.log(`[Strategy: clickNext] Button disabled. Stopping pagination.`);
-                return false;
-            }
-            // 1. Snapshot current state
-            const firstRow = resolve(config.rowSelector, root).first();
-            const oldText = yield firstRow.innerText().catch(() => "");
-            // 2. Click
-            console.log(`[Strategy: clickNext] Clicking next button...`);
-            try {
-                yield nextBtn.click({ timeout: 2000 });
-            }
-            catch (e) {
-                console.warn(`[Strategy: clickNext] Click failed (blocked or detached): ${e}`);
-                return false;
-            }
-            // 3. Smart Wait (Polling)
-            const success = yield waitForCondition(() => __awaiter(void 0, void 0, void 0, function* () {
-                const newText = yield firstRow.innerText().catch(() => "");
-                return newText !== oldText;
-            }), timeout, page);
-            if (!success) {
-                console.warn(`[Strategy: clickNext] Warning: Table content did not change after clicking Next.`);
-            }
-            return success;
-        });
-    },
-    /**
-     * Strategy: Clicks a "Load More" button and waits for the row count to increase.
-     */
-    clickLoadMore: (buttonSelector, timeout = 5000) => {
-        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
-            const loadMoreBtn = resolve(buttonSelector, root).first();
-            if (!(yield loadMoreBtn.isVisible()) || !(yield loadMoreBtn.isEnabled())) {
-                return false;
-            }
-            // 1. Snapshot count
-            const rows = resolve(config.rowSelector, root);
-            const oldCount = yield rows.count();
-            // 2. Click
-            yield loadMoreBtn.click();
-            // 3. Smart Wait (Polling)
-            return yield waitForCondition(() => __awaiter(void 0, void 0, void 0, function* () {
-                const newCount = yield rows.count();
-                return newCount > oldCount;
-            }), timeout, page);
-        });
-    },
-    /**
-     * Strategy: Scrolls to the bottom and waits for more rows to appear.
-     */
-    infiniteScroll: (timeout = 5000) => {
-        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
-            const rows = resolve(config.rowSelector, root);
-            const oldCount = yield rows.count();
-            if (oldCount === 0)
-                return false;
-            // 1. Trigger Scroll
-            yield rows.last().scrollIntoViewIfNeeded();
-            // 2. Smart Wait (Polling)
-            return yield waitForCondition(() => __awaiter(void 0, void 0, void 0, function* () {
-                const newCount = yield rows.count();
-                return newCount > oldCount;
-            }), timeout, page);
-        });
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
     }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+// src/strategies/index.ts
+__exportStar(require("./pagination"), exports);
+__exportStar(require("./sorting"), exports);

package/dist/strategies/pagination.d.ts

@@ -0,0 +1,32 @@
+import type { PaginationStrategy, Selector } from '../types';
+export declare const PaginationStrategies: {
+    /**
+     * Strategy: Clicks a "Next" button and waits for the first row of data to change.
+     */
+    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
+    /**
+     * Strategy: Clicks a "Load More" button and waits for the row count to increase.
+     */
+    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
+    /**
+     * Strategy: Scrolls to the bottom and waits for more rows to appear.
+     */
+    infiniteScroll: (timeout?: number) => PaginationStrategy;
+};
+/**
+ * @deprecated Use `PaginationStrategies` instead. This alias will be removed in a future major version.
+ */
+export declare const TableStrategies: {
+    /**
+     * Strategy: Clicks a "Next" button and waits for the first row of data to change.
+     */
+    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
+    /**
+     * Strategy: Clicks a "Load More" button and waits for the row count to increase.
+     */
+    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
+    /**
+     * Strategy: Scrolls to the bottom and waits for more rows to appear.
+     */
+    infiniteScroll: (timeout?: number) => PaginationStrategy;
+};

package/dist/strategies/pagination.js

@@ -0,0 +1,72 @@
+"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.TableStrategies = exports.PaginationStrategies = void 0;
+const utils_1 = require("../utils");
+exports.PaginationStrategies = {
+    /**
+     * Strategy: Clicks a "Next" button and waits for the first row of data to change.
+     */
+    clickNext: (nextButtonSelector, timeout = 5000) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
+            const nextBtn = resolve(nextButtonSelector, root).first();
+            if (!(yield nextBtn.isVisible()) || !(yield nextBtn.isEnabled())) {
+                return false;
+            }
+            const firstRow = resolve(config.rowSelector, root).first();
+            const oldText = yield firstRow.innerText().catch(() => "");
+            yield nextBtn.click({ timeout: 2000 }).catch(() => { });
+            const success = yield (0, utils_1.waitForCondition)(() => __awaiter(void 0, void 0, void 0, function* () {
+                const newText = yield firstRow.innerText().catch(() => "");
+                return newText !== oldText;
+            }), timeout, page);
+            return success;
+        });
+    },
+    /**
+     * Strategy: Clicks a "Load More" button and waits for the row count to increase.
+     */
+    clickLoadMore: (buttonSelector, timeout = 5000) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
+            const loadMoreBtn = resolve(buttonSelector, root).first();
+            if (!(yield loadMoreBtn.isVisible()) || !(yield loadMoreBtn.isEnabled())) {
+                return false;
+            }
+            const rows = resolve(config.rowSelector, root);
+            const oldCount = yield rows.count();
+            yield loadMoreBtn.click();
+            return yield (0, utils_1.waitForCondition)(() => __awaiter(void 0, void 0, void 0, function* () {
+                const newCount = yield rows.count();
+                return newCount > oldCount;
+            }), timeout, page);
+        });
+    },
+    /**
+     * Strategy: Scrolls to the bottom and waits for more rows to appear.
+     */
+    infiniteScroll: (timeout = 5000) => {
+        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, config, resolve, page }) {
+            const rows = resolve(config.rowSelector, root);
+            const oldCount = yield rows.count();
+            if (oldCount === 0)
+                return false;
+            yield rows.last().scrollIntoViewIfNeeded();
+            return yield (0, utils_1.waitForCondition)(() => __awaiter(void 0, void 0, void 0, function* () {
+                const newCount = yield rows.count();
+                return newCount > oldCount;
+            }), timeout, page);
+        });
+    }
+};
+/**
+ * @deprecated Use `PaginationStrategies` instead. This alias will be removed in a future major version.
+ */
+exports.TableStrategies = exports.PaginationStrategies;

package/dist/strategies/sorting.d.ts

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

package/dist/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 = 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 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 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";
+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

@@ -18,9 +18,33 @@ export type SmartRow = Omit<Locator, 'fill'> & {
   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;
 }
@@ -30,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';
@@ -42,6 +66,7 @@ export interface TableConfig {
   headerSelector?: Selector;
   cellSelector?: Selector;
   pagination?: PaginationStrategy;
+  sorting?: SortingStrategy;
   maxPages?: number;
   /**
    * Hook to rename columns dynamically.
@@ -62,6 +87,14 @@ 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.
@@ -96,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

@@ -8,9 +8,30 @@ export type SmartRow = Omit<Locator, 'fill'> & {
      */
     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;
 }
@@ -18,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';
@@ -29,6 +50,7 @@ export interface TableConfig {
     headerSelector?: Selector;
     cellSelector?: Selector;
     pagination?: PaginationStrategy;
+    sorting?: SortingStrategy;
     maxPages?: number;
     /**
      * Hook to rename columns dynamically.
@@ -52,6 +74,13 @@ 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.
@@ -88,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) => {
@@ -313,6 +357,34 @@ 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* () {
@@ -404,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>;

package/dist/utils.js

@@ -0,0 +1,29 @@
+"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.waitForCondition = void 0;
+/**
+ * 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.
+ */
+const waitForCondition = (predicate, timeout, page) => __awaiter(void 0, void 0, void 0, function* () {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        if (yield predicate()) {
+            return true;
+        }
+        // Wait 100ms before next check (Standard Polling)
+        yield page.waitForTimeout(100).catch(() => new Promise(r => setTimeout(r, 100)));
+    }
+    return false;
+});
+exports.waitForCondition = waitForCondition;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
   "repository": {
     "type": "git",