@cerios/playwright-table 1.1.3 → 2.0.0

package/dist/index.js

@@ -25,8 +25,27 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/playwright-table.ts
-var import_test2 = require("@playwright/test");
+// src/polling.ts
+async function pollTable(fn, options) {
+  var _a, _b;
+  if (!options) {
+    options = {};
+  }
+  const timeout = (_a = options.timeout) != null ? _a : 3e4;
+  const interval = (_b = options.interval) != null ? _b : 100;
+  const startTime = Date.now();
+  let lastError;
+  while (Date.now() - startTime < timeout) {
+    try {
+      await fn();
+      return;
+    } catch (err) {
+      lastError = err;
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+  throw lastError || new Error("Playwright Tables: Polling timeout reached");
+}
 
 // src/cell-content-type.ts
 var CellContentType = /* @__PURE__ */ ((CellContentType2) => {
@@ -37,34 +56,127 @@ var CellContentType = /* @__PURE__ */ ((CellContentType2) => {
 
 // src/table-utils.ts
 var TableUtils = class {
+  constructor() {
+  }
+  /**
+   * Extracts text content from a table cell.
+   * @param cell - The Playwright locator for the cell.
+   * @param cellContentType - The type of content to extract (InnerText or TextContent).
+   * @returns The trimmed text content of the cell, or empty string if no content.
+   * @throws Error if the cell locator doesn't exist in the DOM.
+   */
   static async getCellContent(cell, cellContentType) {
-    const content = cellContentType === "innerText" /* InnerText */ ? await cell.innerText() : await cell.textContent();
-    return (content == null ? void 0 : content.trim()) || "";
+    try {
+      const count = await cell.count();
+      if (count === 0) {
+        throw new Error("Cell locator does not exist in the DOM");
+      }
+      const content = cellContentType === "innerText" /* InnerText */ ? await cell.innerText() : await cell.textContent();
+      return (content == null ? void 0 : content.trim()) || "";
+    } catch (error) {
+      const locatorDescription = this.getLocatorDescription(cell);
+      throw new Error(
+        `Failed to get cell content.
+Locator: ${locatorDescription}
+Content type: ${cellContentType}
+Error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
   }
+  /**
+   * Parses rowspan and colspan attributes from a table cell.
+   * Fetches both attributes in parallel for optimal performance.
+   * @param cell - The Playwright locator for the cell.
+   * @returns Object containing rowspan and colspan values (defaults to 1 if not present).
+   * @throws Error if attributes contain invalid values (non-numeric or less than 1).
+   */
   static async parseSpanAttributes(cell) {
-    return {
-      rowspan: parseInt(await cell.getAttribute("rowspan") || "1", 10),
-      colspan: parseInt(await cell.getAttribute("colspan") || "1", 10)
-    };
+    try {
+      const [rowspanAttr, colspanAttr] = await Promise.all([
+        cell.getAttribute("rowspan"),
+        cell.getAttribute("colspan")
+      ]);
+      const rowspan = parseInt(rowspanAttr || "1", 10);
+      const colspan = parseInt(colspanAttr || "1", 10);
+      if (isNaN(rowspan) || rowspan < 1) {
+        throw new Error(`Invalid rowspan attribute: "${rowspanAttr}". Expected positive integer.`);
+      }
+      if (isNaN(colspan) || colspan < 1) {
+        throw new Error(`Invalid colspan attribute: "${colspanAttr}". Expected positive integer.`);
+      }
+      return { rowspan, colspan };
+    } catch (error) {
+      const locatorDescription = this.getLocatorDescription(cell);
+      throw new Error(
+        `Failed to parse span attributes.
+Locator: ${locatorDescription}
+Error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Extracts a human-readable locator description from a Playwright Locator.
+   * This captures Playwright's internal selector chain for better error messages.
+   * @param locator - The Playwright locator to describe.
+   * @returns A string representation of the locator's selector chain.
+   */
+  static getLocatorDescription(locator) {
+    const locatorString = locator.toString();
+    return locatorString;
   }
 };
 
 // src/table-body.ts
 var TableBody = class {
+  constructor() {
+  }
+  /**
+   * Extracts body rows from a table with proper handling of rowspan and colspan.
+   *
+   * @param rowLocator - The Playwright locator for body rows.
+   * @param columnsSelector - CSS selector for locating columns within rows (e.g., "td").
+   * @param bodyRowsOptions - Optional configuration for cell content extraction.
+   * @param bodyRowsOptions.cellContentType - The type of content to extract (InnerText or TextContent).
+   * @returns Promise resolving to an array of processed body rows.
+   * @throws Error if columnsSelector is empty or if row processing fails.
+   *
+   * @example
+   * const rows = await TableBody.getRows(
+   *   page.locator('tbody tr'),
+   *   'td',
+   *   { cellContentType: CellContentType.TextContent }
+   * );
+   */
   static async getRows(rowLocator, columnsSelector, bodyRowsOptions) {
+    if (!columnsSelector || columnsSelector.trim() === "") {
+      throw new Error("columnsSelector cannot be empty");
+    }
+    const locatorDescription = rowLocator.toString();
     const rows = [];
     const rowsCount = await rowLocator.count();
+    if (rowsCount === 0) {
+      return rows;
+    }
     const spannedCells = {};
     for (let rowIndex = 0; rowIndex < rowsCount; rowIndex++) {
-      const row = rowLocator.nth(rowIndex);
-      const columns = await this.extractColumns(
-        row,
-        columnsSelector,
-        rowIndex,
-        spannedCells,
-        bodyRowsOptions == null ? void 0 : bodyRowsOptions.cellContentType
-      );
-      rows.push(columns);
+      try {
+        const row = rowLocator.nth(rowIndex);
+        const columns = await this.extractColumns(
+          row,
+          columnsSelector,
+          rowIndex,
+          spannedCells,
+          bodyRowsOptions == null ? void 0 : bodyRowsOptions.cellContentType
+        );
+        rows.push(columns);
+      } catch (error) {
+        throw new Error(
+          `Failed to process body row at index ${rowIndex}.
+Body row locator: ${locatorDescription}
+Columns selector: "${columnsSelector}"
+Error: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
     return rows;
   }
@@ -72,35 +184,77 @@ var TableBody = class {
     const columns = [];
     const columnLocators = row.locator(columnsSelector);
     const columnCount = await columnLocators.count();
+    if (columnCount === 0) {
+      this.applySpannedCells(spannedCells, rowIndex, columns);
+      return columns;
+    }
+    const cellDataPromises = [];
     for (let colIndex = 0; colIndex < columnCount; colIndex++) {
-      await this.processColumn(
-        columnLocators.nth(colIndex),
-        colIndex,
-        columns,
-        rowIndex,
-        spannedCells,
-        cellContentType
-      );
+      cellDataPromises.push(this.fetchCellData(columnLocators.nth(colIndex), cellContentType));
+    }
+    const cellDataArray = await Promise.all(cellDataPromises);
+    const spannedPositions = /* @__PURE__ */ new Set();
+    if (spannedCells[rowIndex]) {
+      spannedCells[rowIndex].forEach((_, colIndex) => {
+        if (spannedCells[rowIndex][colIndex] !== void 0) {
+          spannedPositions.add(colIndex);
+        }
+      });
+    }
+    let actualColIndex = 0;
+    for (let domCellIndex = 0; domCellIndex < columnCount; domCellIndex++) {
+      while (spannedPositions.has(actualColIndex)) {
+        actualColIndex++;
+      }
+      const cellData = cellDataArray[domCellIndex];
+      this.processCellData(cellData, actualColIndex, columns, rowIndex, spannedCells);
+      actualColIndex += cellData.colspan;
     }
     this.applySpannedCells(spannedCells, rowIndex, columns);
     return columns;
   }
-  static async processColumn(column, colIndex, columns, rowIndex, spannedCells, cellContentType = "innerText" /* InnerText */) {
-    const content = await TableUtils.getCellContent(column, cellContentType);
-    const { rowspan, colspan } = await TableUtils.parseSpanAttributes(column);
+  /**
+   * Fetches cell content and span attributes in parallel.
+   * This method performs DOM operations that can be parallelized across multiple cells.
+   */
+  static async fetchCellData(column, cellContentType = "innerText" /* InnerText */) {
+    const [content, spanAttributes] = await Promise.all([
+      TableUtils.getCellContent(column, cellContentType),
+      TableUtils.parseSpanAttributes(column)
+    ]);
+    return {
+      content,
+      rowspan: spanAttributes.rowspan,
+      colspan: spanAttributes.colspan
+    };
+  }
+  /**
+   * Processes pre-fetched cell data and applies it to the columns array.
+   * This method is purely computational and doesn't perform any DOM operations.
+   */
+  static processCellData(cellData, colIndex, columns, rowIndex, spannedCells) {
+    const { content, rowspan, colspan } = cellData;
+    if (colIndex < 0) {
+      throw new Error(`Invalid column index: ${colIndex}. Must be non-negative.`);
+    }
+    if (rowIndex < 0) {
+      throw new Error(`Invalid row index: ${rowIndex}. Must be non-negative.`);
+    }
     for (let span = 0; span < colspan; span++) {
       columns[colIndex + span] = content;
     }
     if (rowspan > 1) {
-      this.storeSpannedCells(rowIndex, colIndex, rowspan, content, spannedCells);
+      this.storeSpannedCells(rowIndex, colIndex, rowspan, colspan, content, spannedCells);
     }
   }
-  static storeSpannedCells(rowIndex, colIndex, rowspan, content, spannedCells) {
-    for (let span = 1; span < rowspan; span++) {
-      if (!spannedCells[rowIndex + span]) {
-        spannedCells[rowIndex + span] = [];
+  static storeSpannedCells(rowIndex, colIndex, rowspan, colspan, content, spannedCells) {
+    for (let rowSpan = 1; rowSpan < rowspan; rowSpan++) {
+      if (!spannedCells[rowIndex + rowSpan]) {
+        spannedCells[rowIndex + rowSpan] = [];
+      }
+      for (let colSpan = 0; colSpan < colspan; colSpan++) {
+        spannedCells[rowIndex + rowSpan][colIndex + colSpan] = content;
       }
-      spannedCells[rowIndex + span][colIndex] = content;
     }
   }
   static applySpannedCells(spannedCells, rowIndex, columns) {
@@ -116,14 +270,48 @@ var TableBody = class {
 
 // src/table-header.ts
 var TableHeader = class {
+  constructor() {
+  }
+  /**
+   * Extracts header rows from a table with optional processing for colspan, rowspan, and duplicates.
+   *
+   * @param headerRowLocator - The Playwright locator for header rows.
+   * @param columnsSelector - CSS selector for locating header columns (e.g., "th").
+   * @param headerRowOptions - Optional configuration for header processing.
+   * @returns Promise resolving to an array of processed header rows.
+   * @throws Error if columnsSelector is empty or if no header rows are found.
+   *
+   * @example
+   * const headers = await TableHeader.getRows(
+   *   page.locator('thead tr'),
+   *   'th',
+   *   { duplicateSuffix: true, colspan: { enabled: true } }
+   * );
+   */
   static async getRows(headerRowLocator, columnsSelector, headerRowOptions) {
+    if (!columnsSelector || columnsSelector.trim() === "") {
+      throw new Error("columnsSelector cannot be empty");
+    }
+    const locatorDescription = headerRowLocator.toString();
     const options = this.getDefaultOptions(headerRowOptions);
     const rows = await headerRowLocator.all();
     const headerRows = [];
+    if (rows.length === 0) {
+      return headerRows;
+    }
     const rowSpans = /* @__PURE__ */ new Map();
-    for (const row of rows) {
-      const headerRow = await this.processRow(row, columnsSelector, rowSpans, options);
-      headerRows.push(headerRow);
+    for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+      try {
+        const headerRow = await this.processRow(rows[rowIndex], columnsSelector, rowSpans, options);
+        headerRows.push(headerRow);
+      } catch (error) {
+        throw new Error(
+          `Failed to process header row at index ${rowIndex}.
+Header row locator: ${locatorDescription}
+Columns selector: "${columnsSelector}"
+Error: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
     this.applyColspanOptions(headerRows, options);
     this.applyDuplicateSuffix(headerRows, options);
@@ -144,24 +332,53 @@ var TableHeader = class {
   static async processRow(row, columnsSelector, rowSpans, options) {
     const headerRow = [];
     const cells = await row.locator(columnsSelector).all();
+    if (cells.length === 0) {
+      return headerRow;
+    }
+    const cellDataArray = await Promise.all(cells.map((cell) => this.fetchHeaderCellData(cell, options.cellContentType)));
     let columnIndex = 0;
-    for (const cell of cells) {
-      columnIndex = await this.processCell(cell, headerRow, rowSpans, columnIndex, options);
+    for (let i = 0; i < cellDataArray.length; i++) {
+      columnIndex = this.processHeaderCellData(
+        cellDataArray[i],
+        headerRow,
+        rowSpans,
+        columnIndex,
+        options.emptyCellReplacement
+      );
     }
     this.addRemainingRowSpans(headerRow, rowSpans, columnIndex);
     return headerRow;
   }
-  static async processCell(cell, headerRow, rowSpans, columnIndex, options) {
+  /**
+   * Fetches header cell content and span attributes in parallel.
+   * This method performs DOM operations that can be parallelized across multiple cells.
+   */
+  static async fetchHeaderCellData(cell, cellContentType) {
+    const [text, spanAttributes] = await Promise.all([
+      TableUtils.getCellContent(cell, cellContentType),
+      TableUtils.parseSpanAttributes(cell)
+    ]);
+    return {
+      text,
+      rowspan: spanAttributes.rowspan,
+      colspan: spanAttributes.colspan
+    };
+  }
+  /**
+   * Processes pre-fetched header cell data and applies it to the header row.
+   * This method is purely computational and doesn't perform any DOM operations.
+   */
+  static processHeaderCellData(cellData, headerRow, rowSpans, columnIndex, emptyCellReplacement) {
     while (rowSpans.has(columnIndex)) {
       headerRow.push(rowSpans.get(columnIndex));
       rowSpans.delete(columnIndex);
       columnIndex++;
     }
-    let text = await TableUtils.getCellContent(cell, options.cellContentType);
-    if (!text && options.emptyCellReplacement) {
-      text = "{{Empty}}";
+    let text = cellData.text;
+    if (!text && emptyCellReplacement) {
+      text = this.EMPTY_CELL_PLACEHOLDER;
     }
-    const { colspan, rowspan } = await TableUtils.parseSpanAttributes(cell);
+    const { colspan, rowspan } = cellData;
     headerRow.push(text);
     this.handleColspan(headerRow, text, colspan);
     this.handleRowspan(rowSpans, text, columnIndex, colspan, rowspan);
@@ -169,7 +386,7 @@ var TableHeader = class {
   }
   static handleColspan(headerRow, text, colspan) {
     for (let i = 1; i < colspan; i++) {
-      headerRow.push(`${text}__C${i}`);
+      headerRow.push(`${text}${this.COLSPAN_SUFFIX_PREFIX}${i}`);
     }
   }
   static handleRowspan(rowSpans, text, columnIndex, colspan, rowspan) {
@@ -195,20 +412,15 @@ var TableHeader = class {
     }
   }
   static removeColspanCells(headerRows) {
-    for (const headerRow of headerRows) {
-      for (let i = 0; i < headerRow.length; i++) {
-        if (/__C\d/.test(headerRow[i])) {
-          headerRow.splice(i, 1);
-          i--;
-        }
-      }
+    for (let i = 0; i < headerRows.length; i++) {
+      headerRows[i] = headerRows[i].filter((cell) => !this.COLSPAN_PATTERN.test(cell));
     }
   }
   static removeColspanSuffix(headerRows) {
     for (const headerRow of headerRows) {
       for (let i = 0; i < headerRow.length; i++) {
-        if (/__C\d/.test(headerRow[i])) {
-          headerRow[i] = headerRow[i].replace(/__C\d/, "");
+        if (this.COLSPAN_PATTERN.test(headerRow[i])) {
+          headerRow[i] = headerRow[i].replace(this.COLSPAN_PATTERN, "");
         }
       }
     }
@@ -219,10 +431,10 @@ var TableHeader = class {
       const headerCountMap = /* @__PURE__ */ new Map();
       for (let i = 0; i < headerRow.length; i++) {
         const header = headerRow[i];
-        if (headerCountMap.has(header)) {
-          const count = headerCountMap.get(header);
-          headerRow[i] = `${header}__D${count}`;
-          headerCountMap.set(header, count + 1);
+        const currentCount = headerCountMap.get(header);
+        if (currentCount !== void 0) {
+          headerRow[i] = `${header}${this.DUPLICATE_SUFFIX_PREFIX}${currentCount}`;
+          headerCountMap.set(header, currentCount + 1);
         } else {
           headerCountMap.set(header, 1);
         }
@@ -230,78 +442,10 @@ var TableHeader = class {
     }
   }
 };
-
-// src/table-wait.ts
-var import_test = require("@playwright/test");
-var TableWait = class {
-  static async waitForRows(rowLocator, cellSelector, rowKind, options) {
-    const validateCellsWithContent = async () => {
-      const cells = await rowLocator.locator(cellSelector).all();
-      const cellsWithContent = (await Promise.all(
-        cells.map(async (cell) => {
-          const content = await cell.textContent();
-          return content !== null && content.trim() !== "" ? cell : null;
-        })
-      )).filter((cell) => cell !== null);
-      (0, import_test.expect)(cellsWithContent.length, `No ${rowKind} cells with content found`).toBeGreaterThan(0);
-    };
-    const validateRowAmount = (rows2, expectedAmount) => {
-      (0, import_test.expect)(rows2.length, `Expected ${expectedAmount} ${rowKind} rows, but found ${rows2.length}`).toBe(expectedAmount);
-    };
-    const validateCellCount = async (rows2, expectedCount) => {
-      const rowsWithMatchingCells = (await Promise.all(
-        rows2.map(async (row) => {
-          const cellCount = await row.locator(cellSelector).count();
-          return cellCount === expectedCount ? row : null;
-        })
-      )).filter((row) => row !== null);
-      (0, import_test.expect)(
-        rowsWithMatchingCells.length,
-        `Expected amount of ${expectedCount} ${rowKind} cells for row not found`
-      ).toBeGreaterThan(0);
-    };
-    const validateCellContentCount = async (rows2, expectedContentCount) => {
-      const rowsWithMatchingContent = (await Promise.all(
-        rows2.map(async (row) => {
-          const cells = await row.locator(cellSelector).all();
-          const cellsWithContent = (await Promise.all(
-            cells.map(async (cell) => {
-              const content = await cell.textContent();
-              return content !== null && content.trim() !== "" ? cell : null;
-            })
-          )).filter((cell) => cell !== null);
-          return cellsWithContent.length === expectedContentCount ? row : null;
-        })
-      )).filter((row) => row !== null);
-      (0, import_test.expect)(
-        rowsWithMatchingContent.length,
-        `Expected amount of ${expectedContentCount} ${rowKind} cells with content for row not found`
-      ).toBeGreaterThan(0);
-    };
-    const rows = await rowLocator.all();
-    if (options == null ? void 0 : options.row) {
-      if (options.row.amount) {
-        validateRowAmount(rows, options.row.amount);
-      } else {
-        (0, import_test.expect)(rows.length, `No ${rowKind} rows found`).toBeGreaterThan(0);
-      }
-      if (options.row.cell) {
-        if (options.row.cell.totalCount) {
-          await validateCellCount(rows, options.row.cell.totalCount);
-        }
-        if (options.row.cell.contentCount) {
-          await validateCellContentCount(rows, options.row.cell.contentCount);
-        } else {
-          await validateCellsWithContent();
-        }
-      } else {
-        await validateCellsWithContent();
-      }
-    } else {
-      await validateCellsWithContent();
-    }
-  }
-};
+TableHeader.EMPTY_CELL_PLACEHOLDER = "{{Empty}}";
+TableHeader.COLSPAN_SUFFIX_PREFIX = "__C";
+TableHeader.DUPLICATE_SUFFIX_PREFIX = "__D";
+TableHeader.COLSPAN_PATTERN = /__C\d+/;
 
 // src/playwright-table.ts
 var PlaywrightTable = class {
@@ -336,8 +480,6 @@ var PlaywrightTable = class {
   constructor(_tableLocator, _options) {
     this._tableLocator = _tableLocator;
     this._options = _options;
-    this._headers = [];
-    this._rows = [];
     var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
     this._headerRowLocator = this._tableLocator.locator((_c = (_b = (_a = this._options) == null ? void 0 : _a.header) == null ? void 0 : _b.rowSelector) != null ? _c : "thead>tr");
     this._headerColumnSelector = (_f = (_e = (_d = this._options) == null ? void 0 : _d.header) == null ? void 0 : _e.columnSelector) != null ? _f : "th";
@@ -346,75 +488,145 @@ var PlaywrightTable = class {
   }
   /**
    * Retrieves all header rows of the table.
-   * @param options - Optional parameters for timeout and header row options.
-   * @param options.timeout - Timeout in milliseconds for loading table data.
-   * @param options.headerRowOptions - See {@link HeaderRowOptions} for available options.
+   * @param options - Optional parameters for header row parsing configuration.
    * @returns A promise that resolves to an array of header rows.
+   * @throws Error if no header rows found after table loads.
+   *
+   * @example
+   * // Get headers with colspan enabled
+   * const headers = await table.getHeaderRows({
+   *   colspan: { enabled: true, suffix: true },
+   *   duplicateSuffix: true
+   * });
+   *
+   * @see {@link getMainHeaderRow} for getting only the main header row
+   * @see {@link HeaderRowOptions} for all available configuration options
    */
   async getHeaderRows(options) {
-    await this.load(options);
-    return this._headers;
+    const table = await this.getTable({
+      headerRowOptions: options
+    });
+    return table.headerRows;
   }
   /**
    * Retrieves the main header row of the table.
-   * @param options - Optional parameters for timeout and header row options.
-   * @param options.timeout - Timeout in milliseconds for loading table data.
-   * @param options.headerRowOptions - See {@link HeaderRowOptions} for available options.
+   * By default, uses the last header row if multiple exist. Can be customized via constructor.
+   * @param options - Optional parameters for header row parsing configuration.
    * @returns A promise that resolves to the main header row.
+   * @throws Error if no header rows available.
+   * @throws Error if setMainHeaderRow index is out of bounds (negative or >= header row count).
+   *
+   * @example
+   * // Get main header with custom index set in constructor
+   * const table = new PlaywrightTable(page.locator('table'), {
+   *   header: { setMainHeaderRow: 0 }  // Use first row as main header
+   * });
+   * const mainHeader = await table.getMainHeaderRow();
+   *
+   * @see {@link getHeaderRows} for getting all header rows
    */
   async getMainHeaderRow(options) {
-    await this.load(options);
-    return this.mainHeaderRow();
+    const table = await this.getTable({
+      headerRowOptions: options
+    });
+    return this.mainHeaderRow(table.headerRows);
   }
   /**
    * Retrieves all body rows of the table.
-   * @param options.timout - Timeout in milliseconds for loading table data.
-   * @param options.bodyRowOptions.cellContentType - The content type for the body rows.
+   * @param options - Optional configuration for body row parsing.
+   * @param options.cellContentType - Content extraction type. See {@link CellContentType}. Defaults to InnerText.
    * @returns A promise that resolves to an array of body rows.
+   * @throws Error if no body rows found after table loads.
+   *
+   * @example
+   * // Get body rows with TextContent (includes hidden elements)
+   * const rows = await table.getBodyRows({
+   *   cellContentType: CellContentType.TextContent
+   * });
+   *
+   * @example
+   * // Get body rows with default InnerText
+   * const rows = await table.getBodyRows();
    */
   async getBodyRows(options) {
-    await this.load({
-      timeout: options == null ? void 0 : options.timeout,
-      bodyRowOptions: options == null ? void 0 : options.bodyRowOptions,
+    const table = await this.getTable({
+      bodyRowOptions: options,
       headerRowOptions: {
         colspan: { enabled: true }
       }
     });
-    return this._rows;
+    return table.bodyRows;
   }
   /**
-   * Retrieves a specific cell locator in the body of the table.
+   * Retrieves a specific cell locator in the body of the table by row and column index.
    * @param rowNumber - The row number (0-based index).
-   * @param headerPosition - The header position (0-based index).
+   * @param headerPosition - The column/header position (0-based index).
    * @returns A Playwright Locator for the specified cell.
+   *
+   * @example
+   * // Get cell at row 1, column 2
+   * const cellLocator = table.getBodyCellLocator(1, 2);
+   * await expect(cellLocator).toHaveText('Expected Text');
+   *
+   * @example
+   * // Get first cell in first row
+   * const firstCell = table.getBodyCellLocator(0, 0);
+   * await firstCell.click();
+   *
+   * @see {@link getBodyCellLocatorByRowConditions} for finding cells by content matching
+   * @see {@link getAllBodyCellLocatorsByHeaderIndex} for getting all cells in a column
+   * @see {@link getAllBodyCellLocatorsByHeaderName} for getting all cells under a header
    */
   getBodyCellLocator(rowNumber, headerPosition) {
     return this._bodyRowLocator.nth(rowNumber).locator(this._bodyRowColumnSelector).nth(headerPosition);
   }
   /**
    * Retrieves a cell locator in the body of the table based on row conditions and a target header.
-   * @param conditions - A record of header names and their expected values.
-   * @param targetHeader - The target header name for the desired cell.
-   * @param options - See {@link LoadOptions} for available options.
+   * Finds the first row where all conditions match, then returns the cell in the target column.
+   * @param conditions - An object where keys are header names and values are expected cell contents, or a single [header, value] tuple.
+   * @param targetHeader - The header name of the column containing the cell to retrieve.
+   * @param options - Optional table loading options. See {@link TableOptions}.
    * @returns A promise that resolves to a Playwright Locator for the matching cell.
-   * @throws An error if no matching row is found or if a header is not found.
+   * @throws Error if no row matches all specified conditions.
+   * @throws Error if any condition header or target header is not found in the table.
+   *
+   * @example
+   * // Find cell with multiple conditions
+   * const emailLocator = await table.getBodyCellLocatorByRowConditions(
+   *   { "First name": "John", "Status": "Active" },
+   *   "Email"
+   * );
+   * await expect(emailLocator).toContainText('@example.com');
+   *
+   * @example
+   * // Find cell with single condition using tuple syntax
+   * const actionCell = await table.getBodyCellLocatorByRowConditions(
+   *   ["Username", "john.doe"],
+   *   "Actions"
+   * );
+   * await actionCell.locator('button').click();
+   *
+   * @example
+   * // Find cell with single condition using object syntax
+   * const statusCell = await table.getBodyCellLocatorByRowConditions(
+   *   { "Username": "john.doe" },
+   *   "Status"
+   * );
+   *
+   * @see {@link getBodyCellLocator} for getting cells by direct index
+   * @see {@link getAllBodyCellLocatorsByHeaderName} for getting all cells in a column
    */
   async getBodyCellLocatorByRowConditions(conditions, targetHeader, options) {
     var _a;
-    await this.load(options);
-    const headers = await this.getMainHeaderRow();
-    const targetHeaderIndex = headers.indexOf(targetHeader);
-    if (targetHeaderIndex === -1) {
-      throw new Error(`Header "${targetHeader}" not found.`);
-    }
-    for (let rowIndex = 0; rowIndex < this._rows.length; rowIndex++) {
-      const row = this._rows[rowIndex];
+    const table = await this.getTable(options);
+    const mainHeader = this.mainHeaderRow(table.headerRows);
+    const targetHeaderIndex = this.getHeaderIndex(targetHeader, mainHeader);
+    const conditionsObj = Array.isArray(conditions) ? { [conditions[0]]: conditions[1] } : conditions;
+    for (let rowIndex = 0; rowIndex < table.bodyRows.length; rowIndex++) {
+      const row = table.bodyRows[rowIndex];
       let matches = true;
-      for (const [header, value] of Object.entries(conditions)) {
-        const headerIndex = headers.indexOf(header);
-        if (headerIndex === -1) {
-          throw new Error(`Header "${header}" not found.`);
-        }
+      for (const [header, value] of Object.entries(conditionsObj)) {
+        const headerIndex = this.getHeaderIndex(header, mainHeader);
         const cellValue = (_a = row[headerIndex]) != null ? _a : "";
         if (cellValue !== value) {
           matches = false;
@@ -425,24 +637,42 @@ var PlaywrightTable = class {
         return this.getBodyCellLocator(rowIndex, targetHeaderIndex);
       }
     }
-    throw new Error(`No row found matching conditions: ${JSON.stringify(conditions)}`);
+    throw new Error(
+      `No row found matching conditions: ${JSON.stringify(conditionsObj)}
+Target header: "${targetHeader}"
+Searched ${table.bodyRows.length} rows
+Body row locator: ${this._bodyRowLocator.toString()}`
+    );
   }
   /**
    * Retrieves all cell locators in the body of the table for a specific header name.
-   * @param header - The header name.
-   * @param options - See {@link LoadOptions} for available options.
-   * @returns A promise that resolves to an array of Playwright Locators for the cells.
-   * @throws An error if the header is not found.
+   * Returns locators for every cell in the column identified by the header.
+   * @param header - The header name identifying the column.
+   * @param options - Optional table loading options. See {@link TableOptions}.
+   * @returns A promise that resolves to an array of Playwright Locators for all cells in the column.
+   * @throws Error if the header is not found in the table.
+   *
+   * @example
+   * // Get all cells in the "Status" column
+   * const statusCells = await table.getAllBodyCellLocatorsByHeaderName("Status");
+   * for (const cell of statusCells) {
+   *   await expect(cell).toHaveText(/Active|Inactive/);
+   * }
+   *
+   * @example
+   * // Get text from all cells in "Name" column
+   * const nameCells = await table.getAllBodyCellLocatorsByHeaderName("Name");
+   * const names = await Promise.all(nameCells.map(cell => cell.textContent()));
+   *
+   * @see {@link getAllBodyCellLocatorsByHeaderIndex} for getting cells by column index
+   * @see {@link getBodyCellLocatorByRowConditions} for finding specific cells by content
    */
   async getAllBodyCellLocatorsByHeaderName(header, options) {
-    await this.load(options);
-    const headers = await this.getMainHeaderRow();
-    const headerIndex = headers.indexOf(header);
-    if (headerIndex === -1) {
-      throw new Error(`Header "${header}" not found.`);
-    }
+    const table = await this.getTable(options);
+    const headers = this.mainHeaderRow(table.headerRows);
+    const headerIndex = this.getHeaderIndex(header, headers);
     const locators = [];
-    for (let rowIndex = 0; rowIndex < this._rows.length; rowIndex++) {
+    for (let rowIndex = 0; rowIndex < table.bodyRows.length; rowIndex++) {
       const cellLocator = this.getBodyCellLocator(rowIndex, headerIndex);
       locators.push(cellLocator);
     }
@@ -450,28 +680,68 @@ var PlaywrightTable = class {
   }
   /**
    * Retrieves all cell locators in the body of the table for a specific header index.
-   * @param headerIndex - The header index (0-based).
-   * @param options - See {@link LoadOptions} for available options.
-   * @returns A promise that resolves to an array of Playwright Locators for the cells.
+   * Returns locators for every cell in the column at the specified position.
+   * @param headerIndex - The header/column index (0-based).
+   * @param options - Optional table loading options. See {@link TableOptions}.
+   * @returns A promise that resolves to an array of Playwright Locators for all cells in the column.
+   * @throws Error if the header index is out of bounds (negative or >= column count).
+   *
+   * @example
+   * // Get all cells in the third column (index 2)
+   * const thirdColumnCells = await table.getAllBodyCellLocatorsByHeaderIndex(2);
+   * for (const cell of thirdColumnCells) {
+   *   await expect(cell).toBeVisible();
+   * }
+   *
+   * @example
+   * // Get all cells in first column
+   * const firstColumnCells = await table.getAllBodyCellLocatorsByHeaderIndex(0);
+   * const values = await Promise.all(firstColumnCells.map(c => c.textContent()));
+   *
+   * @see {@link getAllBodyCellLocatorsByHeaderName} for getting cells by header name
+   * @see {@link getBodyCellLocator} for getting a specific cell by row and column index
    */
   async getAllBodyCellLocatorsByHeaderIndex(headerIndex, options) {
-    await this.load(options);
+    const table = await this.getTable(options);
+    const columnCount = this.mainHeaderRow(table.headerRows).length;
+    if (headerIndex < 0 || headerIndex >= columnCount) {
+      throw new Error(
+        `Header index ${headerIndex} out of bounds. Table has ${columnCount} columns.
+Header row locator: ${this._headerRowLocator.toString()}`
+      );
+    }
     const locators = [];
-    for (let rowIndex = 0; rowIndex < this._rows.length; rowIndex++) {
+    for (let rowIndex = 0; rowIndex < table.bodyRows.length; rowIndex++) {
       const cellLocator = this.getBodyCellLocator(rowIndex, headerIndex);
       locators.push(cellLocator);
     }
     return locators;
   }
   /**
-   * Converts the table data into a JSON object.
-   * @param options - See {@link LoadOptions} for available options.
-   * @returns A promise that resolves to a JSON representation of the table.
+   * Converts the table data into a JSON array where each object represents a row.
+   * Keys are header names, values are cell contents.
+   * @param options - Optional table loading options. See {@link TableOptions}.
+   * @returns A promise that resolves to an array of objects representing table rows.
+   * @throws Error if no header rows or body rows found.
+   *
+   * @example
+   * // Convert table to JSON with default options
+   * const data = await table.getJson();
+   * // Result: [{"Name": "John", "Age": "30"}, {"Name": "Jane", "Age": "25"}]
+   *
+   * @example
+   * // Convert with colspan enabled and duplicate suffix
+   * const data = await table.getJson({
+   *   headerRowOptions: {
+   *     colspan: { enabled: true, suffix: true },
+   *     duplicateSuffix: true,
+   *     emptyCellReplacement: true
+   *   }
+   * });
    */
   async getJson(options) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
-    await this.load({
-      timeout: options == null ? void 0 : options.timeout,
+    const table = await this.getTable({
       bodyRowOptions: options == null ? void 0 : options.bodyRowOptions,
       headerRowOptions: {
         colspan: {
@@ -482,8 +752,8 @@ var PlaywrightTable = class {
         emptyCellReplacement: (_j = (_i = options == null ? void 0 : options.headerRowOptions) == null ? void 0 : _i.emptyCellReplacement) != null ? _j : true
       }
     });
-    const headers = this.mainHeaderRow();
-    return this._rows.map((row) => {
+    const headers = this.mainHeaderRow(table.headerRows);
+    return table.bodyRows.map((row) => {
       const rowObj = {};
       headers.forEach((header, index) => {
         rowObj[header] = row[index] || "";
@@ -492,44 +762,289 @@ var PlaywrightTable = class {
     });
   }
   /**
-   * Waits for the header rows to be loaded.
-   * @param options - See {@link WaitForTableRowsOptions} for available options.
-   * @returns A promise that resolves when the header rows are loaded.
+   * Waits for the table body to be empty (no body rows).
+   * @param options - Polling options (timeout, interval, retries).
+   * @returns A promise that resolves when table body is empty.
+   * @throws Error if table is not empty within timeout period.
+   *
+   * @example
+   * // Wait for table to clear after delete operation
+   * await table.waitForEmpty({ timeout: 5000 });
+   *
+   * @see {@link waitForNonEmpty} for waiting until table has data
+   *
+   * @remarks
+   * **Alternative:** Consider using Playwright's `expect.poll` for more flexibility:
+   * ```ts
+   * await expect.poll(async () => (await table.getBodyRows()).length).toBe(0);
+   * ```
    */
-  async waitForHeaderRows(options) {
-    await (0, import_test2.expect)(
-      async () => await TableWait.waitForRows(this._headerRowLocator, this._headerColumnSelector, "header" /* Header */, options)
-    ).toPass({
-      timeout: options == null ? void 0 : options.timeout
-    });
+  async waitForEmpty(options) {
+    await pollTable(async () => {
+      const rows = await this._bodyRowLocator.all();
+      if (rows.length > 0) {
+        throw new Error(
+          `Expected table to be empty, but found ${rows.length} body rows.
+Body row locator: ${this._bodyRowLocator.toString()}`
+        );
+      }
+    }, options);
+  }
+  /**
+   * Waits for the table body to be non-empty (at least one body row with content).
+   * A row is considered valid if it has at least one cell containing text.
+   * @param options - Polling options (timeout, interval, retries).
+   * @returns A promise that resolves when table has at least one body row with content.
+   * @throws Error if table remains empty or has no rows with content within timeout period.
+   *
+   * @example
+   * // Wait for table to populate after search
+   * await table.waitForNonEmpty({ timeout: 5000 });
+   *
+   * @see {@link waitForEmpty} for waiting until table is cleared
+   *
+   * @remarks
+   * **Alternative:** Consider using Playwright's `expect.poll` for more flexibility:
+   * ```ts
+   * await expect.poll(async () => (await table.getBodyRows()).length).toBeGreaterThan(0);
+   * ```
+   */
+  async waitForNonEmpty(options) {
+    await pollTable(async () => {
+      const rows = await this._bodyRowLocator.all();
+      if (rows.length === 0) {
+        throw new Error(
+          `Expected table to be non-empty, but found 0 body rows.
+Body row locator: ${this._bodyRowLocator.toString()}`
+        );
+      }
+      let hasRowWithContent = false;
+      for (const row of rows) {
+        const cells = await row.locator(this._bodyRowColumnSelector).all();
+        for (const cell of cells) {
+          const content = await cell.innerText();
+          if (content.trim().length > 0) {
+            hasRowWithContent = true;
+            break;
+          }
+        }
+        if (hasRowWithContent) break;
+      }
+      if (!hasRowWithContent) {
+        throw new Error(
+          `Expected table to have at least one row with content, but all ${rows.length} rows are empty.
+Body row locator: ${this._bodyRowLocator.toString()}`
+        );
+      }
+    }, options);
+  }
+  /**
+   * Waits for the table body to have exactly N rows.
+   * @param count - The exact number of body rows expected.
+   * @param options - Polling options (timeout, interval, retries).
+   * @returns A promise that resolves when the table has exactly the specified number of rows.
+   * @throws Error if row count doesn't match within timeout period.
+   *
+   * @example
+   * // Wait for exactly 10 rows after pagination
+   * await table.waitForExactRowCount(10, { timeout: 5000 });
+   *
+   * @example
+   * // Verify table has exactly 0 rows (alternative to waitForEmpty)
+   * await table.waitForExactRowCount(0);
+   *
+   * @see {@link getRowCount} for getting current row counts
+   *
+   * @remarks
+   * **Alternative:** Consider using Playwright's `expect.poll` for more flexibility:
+   * ```ts
+   * await expect.poll(async () => (await table.getBodyRows()).length).toBe(10);
+   * ```
+   */
+  async waitForExactRowCount(count, options) {
+    if (count < 0 || !Number.isInteger(count)) {
+      throw new Error(`Row count must be a non-negative integer, got: ${count}`);
+    }
+    await pollTable(async () => {
+      const rows = await this._bodyRowLocator.all();
+      if (rows.length !== count) {
+        throw new Error(
+          `Expected exactly ${count} rows, but found ${rows.length}.
+Body row locator: ${this._bodyRowLocator.toString()}`
+        );
+      }
+    }, options);
+  }
+  /**
+   * Gets the count of header and body rows in the table.
+   * Lightweight method that doesn't fetch cell data, only counts rows.
+   * @returns A promise that resolves to an object with header and body row counts.
+   *
+   * @example
+   * // Get current row counts
+   * const counts = await table.getRowCount();
+   * console.log(`Headers: ${counts.header}, Body: ${counts.body}`);
+   *
+   * @example
+   * // Assert specific row count
+   * const { body } = await table.getRowCount();
+   * expect(body).toBe(10);
+   */
+  async getRowCount() {
+    const [headerRows, bodyRows] = await Promise.all([this._headerRowLocator.all(), this._bodyRowLocator.all()]);
+    return {
+      header: headerRows.length,
+      body: bodyRows.length
+    };
+  }
+  /**
+   * Gets all distinct (unique) values from a specific column.
+   * Returns a sorted array of unique string values, excluding empty values.
+   * @param headerName - The header name of the column to extract distinct values from.
+   * @param options - Optional table loading options. See {@link TableOptions}.
+   * @returns A promise that resolves to a sorted array of distinct values.
+   * @throws Error if the specified header is not found in the table.
+   *
+   * @example
+   * // Get all unique status values
+   * const statuses = await table.getDistinctColumnValues("Status");
+   * // Result: ["Active", "Inactive", "Pending"]
+   *
+   * @example
+   * // Get distinct countries for filtering
+   * const countries = await table.getDistinctColumnValues("Country");
+   * console.log(`Available countries: ${countries.join(", ")}`);
+   *
+   * @example
+   * // Verify expected values exist
+   * const roles = await table.getDistinctColumnValues("Role");
+   * expect(roles).toContain("Admin");
+   * expect(roles).toHaveLength(3);
+   *
+   * @see {@link getAllBodyCellLocatorsByHeaderName} for getting all cell locators in a column
+   * @see {@link getJson} for getting full table data
+   */
+  async getDistinctColumnValues(headerName, options) {
+    var _a;
+    const table = await this.getTable(options);
+    const mainHeader = this.mainHeaderRow(table.headerRows);
+    const headerIndex = this.getHeaderIndex(headerName, mainHeader);
+    const values = /* @__PURE__ */ new Set();
+    for (const row of table.bodyRows) {
+      const value = String((_a = row[headerIndex]) != null ? _a : "").trim();
+      if (value) values.add(value);
+    }
+    return Array.from(values).sort();
   }
   /**
-   * Waits for the body rows to be loaded.
-   * @param options - See {@link WaitForTableRowsOptions} for available options.
-   * @returns A promise that resolves when the body rows are loaded.
+   * Finds the index of the first body row matching the specified conditions.
+   * Returns -1 if no matching row is found.
+   * @param conditions - Record of header names and expected cell values to match.
+   * @param options - Optional table loading options. See {@link TableOptions}.
+   * @returns A promise that resolves to the 0-based index of the first matching row, or -1 if not found.
+   * @throws Error if specified headers don't exist in the table.
+   *
+   * @example
+   * // Find index of row where Status is "Active"
+   * const index = await table.findRowIndex({ Status: "Active" });
+   * if (index >= 0) {
+   *   console.log(`Found at row ${index}`);
+   * }
+   *
+   * @example
+   * // Find row and interact with it
+   * const rowIndex = await table.findRowIndex({ Username: "john.doe" });
+   * if (rowIndex >= 0) {
+   *   const cell = table.getBodyCellLocator(rowIndex, 0);
+   *   await cell.click();
+   * }
+   *
+   * @see {@link getBodyCellLocatorByRowConditions} for getting cell locators from matching rows
+   * @see {@link waitForRowByConditions} for waiting until matching row appears
    */
-  async waitForBodyRows(options) {
-    await (0, import_test2.expect)(
-      async () => await TableWait.waitForRows(this._bodyRowLocator, this._bodyRowColumnSelector, "body" /* Body */, options)
-    ).toPass({
-      timeout: options == null ? void 0 : options.timeout
+  async findRowIndex(conditions, options) {
+    var _a;
+    const table = await this.getTable({
+      headerRowOptions: { colspan: { enabled: true }, ...options == null ? void 0 : options.headerRowOptions },
+      bodyRowOptions: options == null ? void 0 : options.bodyRowOptions
     });
+    const mainHeader = this.mainHeaderRow(table.headerRows);
+    const headerIndices = /* @__PURE__ */ new Map();
+    for (const header of Object.keys(conditions)) {
+      headerIndices.set(header, this.getHeaderIndex(header, mainHeader));
+    }
+    for (let rowIndex = 0; rowIndex < table.bodyRows.length; rowIndex++) {
+      const row = table.bodyRows[rowIndex];
+      let rowMatches = true;
+      for (const [header, expectedValue] of Object.entries(conditions)) {
+        const headerIndex = headerIndices.get(header);
+        const cellValue = String((_a = row[headerIndex]) != null ? _a : "");
+        if (cellValue !== expectedValue) {
+          rowMatches = false;
+          break;
+        }
+      }
+      if (rowMatches) {
+        return rowIndex;
+      }
+    }
+    return -1;
   }
-  async load(options) {
-    await (0, import_test2.expect)(async () => {
-      await TableWait.waitForRows(this._headerRowLocator, this._headerColumnSelector, "header" /* Header */);
-      await TableWait.waitForRows(this._bodyRowLocator, this._bodyRowColumnSelector, "body" /* Body */);
-    }).toPass({ timeout: options == null ? void 0 : options.timeout });
-    this._headers = await TableHeader.getRows(
-      this._headerRowLocator,
-      this._headerColumnSelector,
-      options == null ? void 0 : options.headerRowOptions
-    );
-    this._rows = await TableBody.getRows(this._bodyRowLocator, this._bodyRowColumnSelector, options == null ? void 0 : options.bodyRowOptions);
+  async getTable(options) {
+    const [headerRows, bodyRows] = await Promise.all([
+      TableHeader.getRows(this._headerRowLocator, this._headerColumnSelector, options == null ? void 0 : options.headerRowOptions),
+      TableBody.getRows(this._bodyRowLocator, this._bodyRowColumnSelector, options == null ? void 0 : options.bodyRowOptions)
+    ]);
+    if (headerRows.length === 0) {
+      throw new Error(
+        `No header rows found, is table loaded completely?
+Header row locator: ${this._headerRowLocator.toString()}
+Table locator: ${this._tableLocator.toString()}`
+      );
+    }
+    if (bodyRows.length === 0) {
+      throw new Error(
+        `No body rows found, is table loaded completely?
+Body row locator: ${this._bodyRowLocator.toString()}
+Table locator: ${this._tableLocator.toString()}`
+      );
+    }
+    return { headerRows, bodyRows };
   }
-  mainHeaderRow() {
-    var _a, _b;
-    return ((_b = (_a = this._options) == null ? void 0 : _a.header) == null ? void 0 : _b.setMainHeaderRow) ? this._headers[this._options.header.setMainHeaderRow] : this._headers[this._headers.length - 1];
+  mainHeaderRow(headers) {
+    var _a, _b, _c;
+    if (headers.length === 0) {
+      throw new Error(
+        `No header rows available. Ensure table has been loaded.
+Header row locator: ${this._headerRowLocator.toString()}`
+      );
+    }
+    const headerIndex = (_c = (_b = (_a = this._options) == null ? void 0 : _a.header) == null ? void 0 : _b.setMainHeaderRow) != null ? _c : headers.length - 1;
+    if (headerIndex < 0 || headerIndex >= headers.length) {
+      throw new Error(
+        `Header row index ${headerIndex} out of bounds. Table has ${headers.length} header rows.
+Header row locator: ${this._headerRowLocator.toString()}`
+      );
+    }
+    return headers[headerIndex];
+  }
+  /**
+   * Gets the index of a header in the main header row, throwing an error if not found.
+   * @param header - The header name to find.
+   * @param mainHeader - The main header row to search in.
+   * @returns The 0-based index of the header.
+   * @throws Error if the header is not found.
+   */
+  getHeaderIndex(header, mainHeader) {
+    const index = mainHeader.indexOf(header);
+    if (index === -1) {
+      throw new Error(
+        `Header "${header}" not found.
+Available headers: [${mainHeader.join(", ")}]
+Header row locator: ${this._headerRowLocator.toString()}`
+      );
+    }
+    return index;
   }
 };
 // Annotate the CommonJS export names for ESM import in node: