@cerios/playwright-table 1.1.1 → 1.1.3

package/dist/index.d.mts

@@ -1,14 +1,53 @@
 import { Locator } from '@playwright/test';
 
-type Cell = string | boolean | number;
+/**
+ * Represents a single cell value within a table row.
+ *
+ * @remarks
+ * A `Cell` is a string that holds the textual content of a table cell,
+ * whether in the header or body of the table.
+ */
+type Cell = string;
+/**
+ * Represents a row in the table body, defined as an array of `Cell` objects.
+ *
+ * @remarks
+ * Each `BodyRow` corresponds to a single row in the table's body section.
+ *
+ * @see Cell
+ */
 type BodyRow = Cell[];
-type HeaderRow = string[];
+/**
+ * Represents a row in the table header, defined as an array of `Cell` objects.
+ *
+ * @remarks
+ * Each `HeaderRow` corresponds to a single row in the table's header section.
+ *
+ * @see Cell
+ */
+type HeaderRow = Cell[];
 
+/**
+ * Enum representing the possible types of content that can be extracted from a table cell.
+ *
+ * - `TextContent`: The raw text content of the cell, including hidden elements and extra whitespace.
+ * - `InnerText`: The rendered text content of the cell, as seen by the user, with whitespace collapsed and hidden elements excluded.
+ */
 declare enum CellContentType {
     TextContent = "textContent",
     InnerText = "innerText"
 }
 
+/**
+ * Options for configuring a table header row.
+ *
+ * @property cellContentType - The type of content allowed in the header cell.
+ * @property emptyCellReplacement - If true, replaces empty header cells with a default value.
+ * @property duplicateSuffix - If true, appends a suffix to duplicate header values.
+ * @property colspan - Configuration for column spanning in the header row.
+ * @property colspan.enabled - If true, enables column spanning.
+ * @property colspan.suffix - If true, appends a suffix to spanned columns.
+ */
 type HeaderRowOptions = {
     cellContentType?: CellContentType;
     emptyCellReplacement?: boolean;
@@ -19,6 +58,67 @@ type HeaderRowOptions = {
     };
 };
 
+/**
+ * Options for loading table data, headers, and rows.
+ *
+ * @example
+ * // Wait up to 5 seconds and use custom cell content type for body rows
+ * const options: LoadOptions = {
+ *   timeout: 5000,
+ *   bodyRowOptions: { cellContentType: CellContentType.TextContent },
+ *   headerRowOptions: {
+ *     colspan: { enabled: true, suffix: true },
+ *     duplicateSuffix: true,
+ *     emptyCellReplacement: false,
+ *   },
+ * };
+ * await table.getBodyRows(options);
+ */
+type LoadOptions = {
+    /** Timeout in milliseconds for loading table data. */
+    timeout?: number;
+    /** See {@link HeaderRowOptions} for available options. */
+    headerRowOptions?: HeaderRowOptions;
+    /** Options for parsing body rows. */
+    bodyRowOptions?: {
+        cellContentType?: CellContentType;
+    };
+};
+/**
+ * Options for waiting for table rows to appear or meet certain conditions.
+ *
+ * @example
+ * // Wait for at least 3 body rows, each with 3 cells containing content, within 2 seconds
+ * const waitOptions: WaitForTableRowsOptions = {
+ *   timeout: 2000,
+ *   row: {
+ *     amount: 3,
+ *     cell: {
+ *       totalCount: 3,
+ *       contentCount: 3,
+ *     },
+ *   },
+ * };
+ * await table.waitForBodyRows(waitOptions);
+ */
+type WaitForTableRowsOptions = {
+    /** Timeout in milliseconds for waiting. */
+    timeout?: number;
+    /** Row and cell count/content conditions. */
+    row?: {
+        /** Expected number of rows. */
+        amount?: number;
+        cell?: {
+            /** Expected number of cells per row. */
+            totalCount?: number;
+            /** Expected number of cells with content per row. */
+            contentCount?: number;
+        };
+    };
+};
+/**
+ * Represents a table in Playwright, providing methods to interact with its headers, rows, and cells.
+ */
 declare class PlaywrightTable {
     private readonly _tableLocator;
     private readonly _options?;
@@ -28,6 +128,34 @@ declare class PlaywrightTable {
     private _bodyRowColumnSelector;
     private _headerRowLocator;
     private _headerColumnSelector;
+    /**
+     * Creates an instance of the table handler with customizable selectors for headers and rows.
+     *
+     * @param _tableLocator - The Playwright `Locator` pointing to the root table element.
+     * @param _options - Optional configuration for customizing header and row selectors.
+     * @param _options.header - Options for header row and columns.
+     * @param _options.header.setMainHeaderRow - (Optional) Index of the main header row if multiple header rows exist.
+     * @param _options.header.rowSelector - (Optional) CSS selector for locating header rows. Defaults to `"thead>tr"`.
+     * @param _options.header.columnSelector - (Optional) CSS selector for locating header columns. Defaults to `"th"`.
+     * @param _options.row - Options for body rows and columns.
+     * @param _options.row.rowSelector - (Optional) CSS selector for locating body rows. Defaults to `"tbody>tr"`.
+     * @param _options.row.columnSelector - (Optional) CSS selector for locating body columns. Defaults to `"td"`.
+     *
+     * @example
+     * const table = new PlaywrightTable(
+     *   page.locator('table.my-table'),
+     *   {
+     *     header: {
+     *       rowSelector: 'thead tr.header',
+     *       columnSelector: 'th.header-cell'
+     *     },
+     *     row: {
+     *       rowSelector: 'tbody tr.data-row',
+     *       columnSelector: 'td.data-cell'
+     *     }
+     *   }
+     * );
+     */
     constructor(_tableLocator: Locator, _options?: {
         header?: {
             setMainHeaderRow?: number;
@@ -39,53 +167,80 @@ declare class PlaywrightTable {
             columnSelector?: string;
         };
     } | undefined);
-    getHeaderRows(options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        headerRowOptions?: HeaderRowOptions;
-    }): Promise<HeaderRow[]>;
-    getMainHeaderRow(options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        headerRowOptions?: HeaderRowOptions;
-    }): Promise<HeaderRow>;
-    getBodyRows(options?: {
-        timeout?: number;
-    }): Promise<BodyRow[]>;
+    /**
+     * 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.
+     * @returns A promise that resolves to an array of header rows.
+     */
+    getHeaderRows(options?: Pick<LoadOptions, "timeout" | "headerRowOptions">): Promise<HeaderRow[]>;
+    /**
+     * 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.
+     * @returns A promise that resolves to the main header row.
+     */
+    getMainHeaderRow(options?: Pick<LoadOptions, "timeout" | "headerRowOptions">): Promise<HeaderRow>;
+    /**
+     * 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.
+     * @returns A promise that resolves to an array of body rows.
+     */
+    getBodyRows(options?: Pick<LoadOptions, "timeout" | "bodyRowOptions">): Promise<BodyRow[]>;
+    /**
+     * Retrieves a specific cell locator in the body of the table.
+     * @param rowNumber - The row number (0-based index).
+     * @param headerPosition - The header position (0-based index).
+     * @returns A Playwright Locator for the specified cell.
+     */
     getBodyCellLocator(rowNumber: number, headerPosition: number): Locator;
-    getBodyCellLocatorByRowConditions(conditions: Record<string, string>, targetHeader: string, options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        colspanEnabled?: boolean;
-    }): Promise<Locator>;
-    getAllBodyCellLocatorsByHeaderName(header: string, options?: {
-        timeout?: number;
-    }): Promise<Locator[]>;
-    getAllBodyCellLocatorsByHeaderIndex(headerIndex: number): Promise<Locator[]>;
-    getJson(options?: {
-        timeout?: number;
-    }): Promise<any>;
-    waitForHeaderRows(options?: {
-        timeout?: number;
-        row?: {
-            amount?: number;
-            cell?: {
-                totalCount?: number;
-                contentCount?: number;
-            };
-        };
-    }): Promise<void>;
-    waitForBodyRows(options?: {
-        timeout?: number;
-        row?: {
-            amount?: number;
-            cell?: {
-                totalCount?: number;
-                contentCount?: number;
-            };
-        };
-    }): Promise<void>;
+    /**
+     * 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.
+     * @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.
+     */
+    getBodyCellLocatorByRowConditions(conditions: Record<string, string>, targetHeader: string, options?: LoadOptions): Promise<Locator>;
+    /**
+     * 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.
+     */
+    getAllBodyCellLocatorsByHeaderName(header: string, options?: LoadOptions): Promise<Locator[]>;
+    /**
+     * 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.
+     */
+    getAllBodyCellLocatorsByHeaderIndex(headerIndex: number, options?: LoadOptions): Promise<Locator[]>;
+    /**
+     * 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.
+     */
+    getJson(options?: LoadOptions): Promise<any>;
+    /**
+     * 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.
+     */
+    waitForHeaderRows(options?: WaitForTableRowsOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    waitForBodyRows(options?: WaitForTableRowsOptions): Promise<void>;
     private load;
+    private mainHeaderRow;
 }
 
-export { type BodyRow, type Cell, CellContentType, type HeaderRow, type HeaderRowOptions, PlaywrightTable };
+export { type BodyRow, type Cell, CellContentType, type HeaderRow, type HeaderRowOptions, type LoadOptions, PlaywrightTable, type WaitForTableRowsOptions };

package/dist/index.d.ts

@@ -1,14 +1,53 @@
 import { Locator } from '@playwright/test';
 
-type Cell = string | boolean | number;
+/**
+ * Represents a single cell value within a table row.
+ *
+ * @remarks
+ * A `Cell` is a string that holds the textual content of a table cell,
+ * whether in the header or body of the table.
+ */
+type Cell = string;
+/**
+ * Represents a row in the table body, defined as an array of `Cell` objects.
+ *
+ * @remarks
+ * Each `BodyRow` corresponds to a single row in the table's body section.
+ *
+ * @see Cell
+ */
 type BodyRow = Cell[];
-type HeaderRow = string[];
+/**
+ * Represents a row in the table header, defined as an array of `Cell` objects.
+ *
+ * @remarks
+ * Each `HeaderRow` corresponds to a single row in the table's header section.
+ *
+ * @see Cell
+ */
+type HeaderRow = Cell[];
 
+/**
+ * Enum representing the possible types of content that can be extracted from a table cell.
+ *
+ * - `TextContent`: The raw text content of the cell, including hidden elements and extra whitespace.
+ * - `InnerText`: The rendered text content of the cell, as seen by the user, with whitespace collapsed and hidden elements excluded.
+ */
 declare enum CellContentType {
     TextContent = "textContent",
     InnerText = "innerText"
 }
 
+/**
+ * Options for configuring a table header row.
+ *
+ * @property cellContentType - The type of content allowed in the header cell.
+ * @property emptyCellReplacement - If true, replaces empty header cells with a default value.
+ * @property duplicateSuffix - If true, appends a suffix to duplicate header values.
+ * @property colspan - Configuration for column spanning in the header row.
+ * @property colspan.enabled - If true, enables column spanning.
+ * @property colspan.suffix - If true, appends a suffix to spanned columns.
+ */
 type HeaderRowOptions = {
     cellContentType?: CellContentType;
     emptyCellReplacement?: boolean;
@@ -19,6 +58,67 @@ type HeaderRowOptions = {
     };
 };
 
+/**
+ * Options for loading table data, headers, and rows.
+ *
+ * @example
+ * // Wait up to 5 seconds and use custom cell content type for body rows
+ * const options: LoadOptions = {
+ *   timeout: 5000,
+ *   bodyRowOptions: { cellContentType: CellContentType.TextContent },
+ *   headerRowOptions: {
+ *     colspan: { enabled: true, suffix: true },
+ *     duplicateSuffix: true,
+ *     emptyCellReplacement: false,
+ *   },
+ * };
+ * await table.getBodyRows(options);
+ */
+type LoadOptions = {
+    /** Timeout in milliseconds for loading table data. */
+    timeout?: number;
+    /** See {@link HeaderRowOptions} for available options. */
+    headerRowOptions?: HeaderRowOptions;
+    /** Options for parsing body rows. */
+    bodyRowOptions?: {
+        cellContentType?: CellContentType;
+    };
+};
+/**
+ * Options for waiting for table rows to appear or meet certain conditions.
+ *
+ * @example
+ * // Wait for at least 3 body rows, each with 3 cells containing content, within 2 seconds
+ * const waitOptions: WaitForTableRowsOptions = {
+ *   timeout: 2000,
+ *   row: {
+ *     amount: 3,
+ *     cell: {
+ *       totalCount: 3,
+ *       contentCount: 3,
+ *     },
+ *   },
+ * };
+ * await table.waitForBodyRows(waitOptions);
+ */
+type WaitForTableRowsOptions = {
+    /** Timeout in milliseconds for waiting. */
+    timeout?: number;
+    /** Row and cell count/content conditions. */
+    row?: {
+        /** Expected number of rows. */
+        amount?: number;
+        cell?: {
+            /** Expected number of cells per row. */
+            totalCount?: number;
+            /** Expected number of cells with content per row. */
+            contentCount?: number;
+        };
+    };
+};
+/**
+ * Represents a table in Playwright, providing methods to interact with its headers, rows, and cells.
+ */
 declare class PlaywrightTable {
     private readonly _tableLocator;
     private readonly _options?;
@@ -28,6 +128,34 @@ declare class PlaywrightTable {
     private _bodyRowColumnSelector;
     private _headerRowLocator;
     private _headerColumnSelector;
+    /**
+     * Creates an instance of the table handler with customizable selectors for headers and rows.
+     *
+     * @param _tableLocator - The Playwright `Locator` pointing to the root table element.
+     * @param _options - Optional configuration for customizing header and row selectors.
+     * @param _options.header - Options for header row and columns.
+     * @param _options.header.setMainHeaderRow - (Optional) Index of the main header row if multiple header rows exist.
+     * @param _options.header.rowSelector - (Optional) CSS selector for locating header rows. Defaults to `"thead>tr"`.
+     * @param _options.header.columnSelector - (Optional) CSS selector for locating header columns. Defaults to `"th"`.
+     * @param _options.row - Options for body rows and columns.
+     * @param _options.row.rowSelector - (Optional) CSS selector for locating body rows. Defaults to `"tbody>tr"`.
+     * @param _options.row.columnSelector - (Optional) CSS selector for locating body columns. Defaults to `"td"`.
+     *
+     * @example
+     * const table = new PlaywrightTable(
+     *   page.locator('table.my-table'),
+     *   {
+     *     header: {
+     *       rowSelector: 'thead tr.header',
+     *       columnSelector: 'th.header-cell'
+     *     },
+     *     row: {
+     *       rowSelector: 'tbody tr.data-row',
+     *       columnSelector: 'td.data-cell'
+     *     }
+     *   }
+     * );
+     */
     constructor(_tableLocator: Locator, _options?: {
         header?: {
             setMainHeaderRow?: number;
@@ -39,53 +167,80 @@ declare class PlaywrightTable {
             columnSelector?: string;
         };
     } | undefined);
-    getHeaderRows(options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        headerRowOptions?: HeaderRowOptions;
-    }): Promise<HeaderRow[]>;
-    getMainHeaderRow(options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        headerRowOptions?: HeaderRowOptions;
-    }): Promise<HeaderRow>;
-    getBodyRows(options?: {
-        timeout?: number;
-    }): Promise<BodyRow[]>;
+    /**
+     * 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.
+     * @returns A promise that resolves to an array of header rows.
+     */
+    getHeaderRows(options?: Pick<LoadOptions, "timeout" | "headerRowOptions">): Promise<HeaderRow[]>;
+    /**
+     * 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.
+     * @returns A promise that resolves to the main header row.
+     */
+    getMainHeaderRow(options?: Pick<LoadOptions, "timeout" | "headerRowOptions">): Promise<HeaderRow>;
+    /**
+     * 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.
+     * @returns A promise that resolves to an array of body rows.
+     */
+    getBodyRows(options?: Pick<LoadOptions, "timeout" | "bodyRowOptions">): Promise<BodyRow[]>;
+    /**
+     * Retrieves a specific cell locator in the body of the table.
+     * @param rowNumber - The row number (0-based index).
+     * @param headerPosition - The header position (0-based index).
+     * @returns A Playwright Locator for the specified cell.
+     */
     getBodyCellLocator(rowNumber: number, headerPosition: number): Locator;
-    getBodyCellLocatorByRowConditions(conditions: Record<string, string>, targetHeader: string, options?: {
-        timeout?: number;
-        duplicateSuffix?: boolean;
-        colspanEnabled?: boolean;
-    }): Promise<Locator>;
-    getAllBodyCellLocatorsByHeaderName(header: string, options?: {
-        timeout?: number;
-    }): Promise<Locator[]>;
-    getAllBodyCellLocatorsByHeaderIndex(headerIndex: number): Promise<Locator[]>;
-    getJson(options?: {
-        timeout?: number;
-    }): Promise<any>;
-    waitForHeaderRows(options?: {
-        timeout?: number;
-        row?: {
-            amount?: number;
-            cell?: {
-                totalCount?: number;
-                contentCount?: number;
-            };
-        };
-    }): Promise<void>;
-    waitForBodyRows(options?: {
-        timeout?: number;
-        row?: {
-            amount?: number;
-            cell?: {
-                totalCount?: number;
-                contentCount?: number;
-            };
-        };
-    }): Promise<void>;
+    /**
+     * 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.
+     * @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.
+     */
+    getBodyCellLocatorByRowConditions(conditions: Record<string, string>, targetHeader: string, options?: LoadOptions): Promise<Locator>;
+    /**
+     * 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.
+     */
+    getAllBodyCellLocatorsByHeaderName(header: string, options?: LoadOptions): Promise<Locator[]>;
+    /**
+     * 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.
+     */
+    getAllBodyCellLocatorsByHeaderIndex(headerIndex: number, options?: LoadOptions): Promise<Locator[]>;
+    /**
+     * 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.
+     */
+    getJson(options?: LoadOptions): Promise<any>;
+    /**
+     * 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.
+     */
+    waitForHeaderRows(options?: WaitForTableRowsOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    waitForBodyRows(options?: WaitForTableRowsOptions): Promise<void>;
     private load;
+    private mainHeaderRow;
 }
 
-export { type BodyRow, type Cell, CellContentType, type HeaderRow, type HeaderRowOptions, PlaywrightTable };
+export { type BodyRow, type Cell, CellContentType, type HeaderRow, type HeaderRowOptions, type LoadOptions, PlaywrightTable, type WaitForTableRowsOptions };