@cerios/playwright-table 2.0.0 → 2.0.2

package/README.md

@@ -140,6 +140,8 @@ console.log(headers);
   cellContentType?: CellContentType.InnerText | CellContentType.TextContent, // Default: InnerText
   emptyCellReplacement?: boolean,  // Replace empty cells with "{{Empty}}" (default: false)
   duplicateSuffix?: boolean,        // Add suffix to duplicate headers (default: false)
+	normalizeWhitespace?: boolean,    // Collapse internal whitespace/newlines (default: false)
+	stripIconGlyphs?: boolean,        // Remove icon-font private-use glyphs from headers (default: false)
   colspan?: {
     enabled?: boolean,              // Enable colspan parsing (default: false)
     suffix?: boolean                // Add suffix to colspan cells (default: false)
@@ -185,7 +187,7 @@ Retrieves all body rows with support for rowspan and colspan.
 
 **Parameters:**
 
-- `options?: { cellContentType?: CellContentType }` - Content extraction type
+- `options?: TableOptions` - Full table options (`bodyRowOptions`, `headerRowOptions`) and legacy `cellContentType` shortcut
 
 **Returns:** `Promise<BodyRow[]>` - Array of body rows
 
@@ -194,9 +196,20 @@ Retrieves all body rows with support for rowspan and colspan.
 **Example:**
 
 ```ts
+// Legacy shortcut
 const rows = await table.getBodyRows({
 	cellContentType: CellContentType.TextContent, // Include hidden elements
 });
+
+// Full table options (useful for custom grids with noisy headers)
+const rowsWithOptions = await table.getBodyRows({
+	bodyRowOptions: { cellContentType: CellContentType.InnerText },
+	headerRowOptions: {
+		normalizeWhitespace: true,
+		stripIconGlyphs: true,
+	},
+});
+
 console.log(rows);
 // Output: [["John", "30", "NYC"], ["Jane", "25", "LA"]]
 ```
@@ -206,6 +219,8 @@ console.log(rows);
 - `CellContentType.InnerText` - Rendered text (default, excludes hidden elements)
 - `CellContentType.TextContent` - Raw text content (includes hidden elements)
 
+Header sanitization options (`normalizeWhitespace`, `stripIconGlyphs`) can be used in all methods that accept `HeaderRowOptions` or `TableOptions`, such as `getHeaderRows`, `getMainHeaderRow`, `getJson`, `findRowIndex`, and `getBodyCellLocatorByRowConditions`.
+
 ---
 
 ### 4. `getBodyCellLocator(rowNumber, headerPosition)`
@@ -669,6 +684,25 @@ const divTable = new PlaywrightTable(page.locator(".divTable"), {
 });
 ```
 
+### ARIA Treegrid Tables
+
+For `role="treegrid"` structures, make sure header and body row selectors are scoped to different containers.
+If both use the same selector (for example `div[role='row']`), header rows can be included in body rows.
+
+```ts
+const table = new PlaywrightTable(page.locator("[role='treegrid']"), {
+	header: {
+		setMainHeaderRow: 0,
+		rowSelector: "[data-kind='header-group'] > div[role='row']",
+		columnSelector: "div[role='columnheader']",
+	},
+	row: {
+		rowSelector: "[data-kind='body-group'] > div[role='row']",
+		columnSelector: "div[role='gridcell']",
+	},
+});
+```
+
 ### Header Row Options
 
 Control how headers are processed:
@@ -678,6 +712,8 @@ const headers = await table.getHeaderRows({
 	cellContentType: CellContentType.TextContent, // Include hidden text
 	emptyCellReplacement: true, // Replace "" with "{{Empty}}"
 	duplicateSuffix: true, // "Name", "Name__D1", "Name__D2"
+	normalizeWhitespace: true, // "Account\nName" -> "Account Name"
+	stripIconGlyphs: true, // Removes private-use icon glyph chars from header text
 	colspan: {
 		enabled: true, // Process colspan attributes
 		suffix: true, // "Col", "Col__C1", "Col__C2"

package/dist/index.d.mts

@@ -61,6 +61,8 @@ type HeaderRowOptions = {
         enabled?: boolean;
         suffix?: boolean;
     };
+    normalizeWhitespace?: boolean;
+    stripIconGlyphs?: boolean;
 };
 
 /**
@@ -85,6 +87,8 @@ type TableOptions = {
     bodyRowOptions?: {
         cellContentType?: CellContentType;
     };
+    /** @deprecated Use `bodyRowOptions.cellContentType` instead. */
+    cellContentType?: CellContentType;
 };
 /**
  * Represents a table in Playwright, providing methods to interact with its headers, rows, and cells.
@@ -172,8 +176,10 @@ declare class PlaywrightTable {
     getMainHeaderRow(options?: HeaderRowOptions): Promise<HeaderRow>;
     /**
      * Retrieves all body rows of the table.
-     * @param options - Optional configuration for body row parsing.
-     * @param options.cellContentType - Content extraction type. See {@link CellContentType}. Defaults to InnerText.
+     * @param options - Optional table or body-row configuration.
+     * @param options.cellContentType - Legacy shortcut for body row content extraction. See {@link CellContentType}.
+     * @param options.bodyRowOptions - Body row parsing options.
+     * @param options.headerRowOptions - Header parsing options used when resolving row/colspan layouts.
      * @returns A promise that resolves to an array of body rows.
      * @throws Error if no body rows found after table loads.
      *
@@ -186,10 +192,15 @@ declare class PlaywrightTable {
      * @example
      * // Get body rows with default InnerText
      * const rows = await table.getBodyRows();
+     *
+     * @example
+     * // Use full table options (for example to sanitize noisy treegrid headers)
+     * const rows = await table.getBodyRows({
+     *   bodyRowOptions: { cellContentType: CellContentType.InnerText },
+     *   headerRowOptions: { normalizeWhitespace: true, stripIconGlyphs: true }
+     * });
      */
-    getBodyRows(options?: {
-        cellContentType?: CellContentType;
-    }): Promise<BodyRow[]>;
+    getBodyRows(options?: TableOptions): Promise<BodyRow[]>;
     /**
      * Retrieves a specific cell locator in the body of the table by row and column index.
      * @param rowNumber - The row number (0-based index).
@@ -457,6 +468,10 @@ declare class PlaywrightTable {
      */
     findRowIndex(conditions: Record<string, string>, options?: TableOptions): Promise<number>;
     private getTable;
+    private normalizeGetBodyRowsOptions;
+    private resolveHeaderRowOptionsForJsonKeys;
+    private resolveTableOptionsForHeaderKeyMethods;
+    private resolveHeaderRowOptions;
     private mainHeaderRow;
     /**
      * Gets the index of a header in the main header row, throwing an error if not found.

package/dist/index.d.ts

@@ -61,6 +61,8 @@ type HeaderRowOptions = {
         enabled?: boolean;
         suffix?: boolean;
     };
+    normalizeWhitespace?: boolean;
+    stripIconGlyphs?: boolean;
 };
 
 /**
@@ -85,6 +87,8 @@ type TableOptions = {
     bodyRowOptions?: {
         cellContentType?: CellContentType;
     };
+    /** @deprecated Use `bodyRowOptions.cellContentType` instead. */
+    cellContentType?: CellContentType;
 };
 /**
  * Represents a table in Playwright, providing methods to interact with its headers, rows, and cells.
@@ -172,8 +176,10 @@ declare class PlaywrightTable {
     getMainHeaderRow(options?: HeaderRowOptions): Promise<HeaderRow>;
     /**
      * Retrieves all body rows of the table.
-     * @param options - Optional configuration for body row parsing.
-     * @param options.cellContentType - Content extraction type. See {@link CellContentType}. Defaults to InnerText.
+     * @param options - Optional table or body-row configuration.
+     * @param options.cellContentType - Legacy shortcut for body row content extraction. See {@link CellContentType}.
+     * @param options.bodyRowOptions - Body row parsing options.
+     * @param options.headerRowOptions - Header parsing options used when resolving row/colspan layouts.
      * @returns A promise that resolves to an array of body rows.
      * @throws Error if no body rows found after table loads.
      *
@@ -186,10 +192,15 @@ declare class PlaywrightTable {
      * @example
      * // Get body rows with default InnerText
      * const rows = await table.getBodyRows();
+     *
+     * @example
+     * // Use full table options (for example to sanitize noisy treegrid headers)
+     * const rows = await table.getBodyRows({
+     *   bodyRowOptions: { cellContentType: CellContentType.InnerText },
+     *   headerRowOptions: { normalizeWhitespace: true, stripIconGlyphs: true }
+     * });
      */
-    getBodyRows(options?: {
-        cellContentType?: CellContentType;
-    }): Promise<BodyRow[]>;
+    getBodyRows(options?: TableOptions): Promise<BodyRow[]>;
     /**
      * Retrieves a specific cell locator in the body of the table by row and column index.
      * @param rowNumber - The row number (0-based index).
@@ -457,6 +468,10 @@ declare class PlaywrightTable {
      */
     findRowIndex(conditions: Record<string, string>, options?: TableOptions): Promise<number>;
     private getTable;
+    private normalizeGetBodyRowsOptions;
+    private resolveHeaderRowOptionsForJsonKeys;
+    private resolveTableOptionsForHeaderKeyMethods;
+    private resolveHeaderRowOptions;
     private mainHeaderRow;
     /**
      * Gets the index of a header in the main header row, throwing an error if not found.

package/dist/index.js

@@ -318,14 +318,16 @@ Error: ${error instanceof Error ? error.message : String(error)}`
     return headerRows;
   }
   static getDefaultOptions(options) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
     return {
       cellContentType: (_a = options == null ? void 0 : options.cellContentType) != null ? _a : "innerText" /* InnerText */,
       emptyCellReplacement: (_b = options == null ? void 0 : options.emptyCellReplacement) != null ? _b : false,
       duplicateSuffix: (_c = options == null ? void 0 : options.duplicateSuffix) != null ? _c : false,
+      normalizeWhitespace: (_d = options == null ? void 0 : options.normalizeWhitespace) != null ? _d : false,
+      stripIconGlyphs: (_e = options == null ? void 0 : options.stripIconGlyphs) != null ? _e : false,
       colspan: {
-        enabled: (_e = (_d = options == null ? void 0 : options.colspan) == null ? void 0 : _d.enabled) != null ? _e : false,
-        suffix: (_g = (_f = options == null ? void 0 : options.colspan) == null ? void 0 : _f.suffix) != null ? _g : false
+        enabled: (_g = (_f = options == null ? void 0 : options.colspan) == null ? void 0 : _f.enabled) != null ? _g : false,
+        suffix: (_i = (_h = options == null ? void 0 : options.colspan) == null ? void 0 : _h.suffix) != null ? _i : false
       }
     };
   }
@@ -335,7 +337,11 @@ Error: ${error instanceof Error ? error.message : String(error)}`
     if (cells.length === 0) {
       return headerRow;
     }
-    const cellDataArray = await Promise.all(cells.map((cell) => this.fetchHeaderCellData(cell, options.cellContentType)));
+    const cellDataArray = await Promise.all(
+      cells.map(
+        (cell) => this.fetchHeaderCellData(cell, options.cellContentType, options.normalizeWhitespace, options.stripIconGlyphs)
+      )
+    );
     let columnIndex = 0;
     for (let i = 0; i < cellDataArray.length; i++) {
       columnIndex = this.processHeaderCellData(
@@ -353,17 +359,27 @@ Error: ${error instanceof Error ? error.message : String(error)}`
    * 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) {
+  static async fetchHeaderCellData(cell, cellContentType, normalizeWhitespace, stripIconGlyphs) {
     const [text, spanAttributes] = await Promise.all([
       TableUtils.getCellContent(cell, cellContentType),
       TableUtils.parseSpanAttributes(cell)
     ]);
     return {
-      text,
+      text: this.sanitizeHeaderText(text, normalizeWhitespace, stripIconGlyphs),
       rowspan: spanAttributes.rowspan,
       colspan: spanAttributes.colspan
     };
   }
+  static sanitizeHeaderText(text, normalizeWhitespace, stripIconGlyphs) {
+    let result = text;
+    if (stripIconGlyphs) {
+      result = result.replace(this.ICON_GLYPH_PATTERN, "");
+    }
+    if (normalizeWhitespace) {
+      result = result.replace(this.CONTROL_WHITESPACE_PATTERN, " ").replace(this.WHITESPACE_PATTERN, " ");
+    }
+    return result.trim();
+  }
   /**
    * 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.
@@ -446,6 +462,9 @@ TableHeader.EMPTY_CELL_PLACEHOLDER = "{{Empty}}";
 TableHeader.COLSPAN_SUFFIX_PREFIX = "__C";
 TableHeader.DUPLICATE_SUFFIX_PREFIX = "__D";
 TableHeader.COLSPAN_PATTERN = /__C\d+/;
+TableHeader.ICON_GLYPH_PATTERN = /[\uE000-\uF8FF\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]/gu;
+TableHeader.CONTROL_WHITESPACE_PATTERN = /[\p{Cc}\p{Zl}\p{Zp}]+/gu;
+TableHeader.WHITESPACE_PATTERN = /\s+/g;
 
 // src/playwright-table.ts
 var PlaywrightTable = class {
@@ -480,11 +499,18 @@ var PlaywrightTable = class {
   constructor(_tableLocator, _options) {
     this._tableLocator = _tableLocator;
     this._options = _options;
-    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";
-    this._bodyRowLocator = this._tableLocator.locator((_i = (_h = (_g = this._options) == null ? void 0 : _g.row) == null ? void 0 : _h.rowSelector) != null ? _i : "tbody>tr");
-    this._bodyRowColumnSelector = (_l = (_k = (_j = this._options) == null ? void 0 : _j.row) == null ? void 0 : _k.columnSelector) != null ? _l : "td";
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
+    const headerRowSelector = (_b = (_a = this._options) == null ? void 0 : _a.header) == null ? void 0 : _b.rowSelector;
+    const bodyRowSelector = (_d = (_c = this._options) == null ? void 0 : _c.row) == null ? void 0 : _d.rowSelector;
+    if (headerRowSelector && bodyRowSelector && headerRowSelector === bodyRowSelector) {
+      console.warn(
+        `PlaywrightTable: header.rowSelector and row.rowSelector are identical ("${headerRowSelector}"). This can cause header rows to be included in body rows. Consider scoping selectors to separate row groups.`
+      );
+    }
+    this._headerRowLocator = this._tableLocator.locator((_g = (_f = (_e = this._options) == null ? void 0 : _e.header) == null ? void 0 : _f.rowSelector) != null ? _g : "thead>tr");
+    this._headerColumnSelector = (_j = (_i = (_h = this._options) == null ? void 0 : _h.header) == null ? void 0 : _i.columnSelector) != null ? _j : "th";
+    this._bodyRowLocator = this._tableLocator.locator((_m = (_l = (_k = this._options) == null ? void 0 : _k.row) == null ? void 0 : _l.rowSelector) != null ? _m : "tbody>tr");
+    this._bodyRowColumnSelector = (_p = (_o = (_n = this._options) == null ? void 0 : _n.row) == null ? void 0 : _o.columnSelector) != null ? _p : "td";
   }
   /**
    * Retrieves all header rows of the table.
@@ -533,8 +559,10 @@ var PlaywrightTable = class {
   }
   /**
    * Retrieves all body rows of the table.
-   * @param options - Optional configuration for body row parsing.
-   * @param options.cellContentType - Content extraction type. See {@link CellContentType}. Defaults to InnerText.
+   * @param options - Optional table or body-row configuration.
+   * @param options.cellContentType - Legacy shortcut for body row content extraction. See {@link CellContentType}.
+   * @param options.bodyRowOptions - Body row parsing options.
+   * @param options.headerRowOptions - Header parsing options used when resolving row/colspan layouts.
    * @returns A promise that resolves to an array of body rows.
    * @throws Error if no body rows found after table loads.
    *
@@ -547,13 +575,21 @@ var PlaywrightTable = class {
    * @example
    * // Get body rows with default InnerText
    * const rows = await table.getBodyRows();
+   *
+   * @example
+   * // Use full table options (for example to sanitize noisy treegrid headers)
+   * const rows = await table.getBodyRows({
+   *   bodyRowOptions: { cellContentType: CellContentType.InnerText },
+   *   headerRowOptions: { normalizeWhitespace: true, stripIconGlyphs: true }
+   * });
    */
   async getBodyRows(options) {
+    const tableOptions = this.normalizeGetBodyRowsOptions(options);
     const table = await this.getTable({
-      bodyRowOptions: options,
-      headerRowOptions: {
-        colspan: { enabled: true }
-      }
+      bodyRowOptions: tableOptions.bodyRowOptions,
+      headerRowOptions: this.resolveHeaderRowOptions(tableOptions.headerRowOptions, {
+        forceColspanEnabled: true
+      })
     });
     return table.bodyRows;
   }
@@ -618,7 +654,7 @@ var PlaywrightTable = class {
    */
   async getBodyCellLocatorByRowConditions(conditions, targetHeader, options) {
     var _a;
-    const table = await this.getTable(options);
+    const table = await this.getTable(this.resolveTableOptionsForHeaderKeyMethods(options));
     const mainHeader = this.mainHeaderRow(table.headerRows);
     const targetHeaderIndex = this.getHeaderIndex(targetHeader, mainHeader);
     const conditionsObj = Array.isArray(conditions) ? { [conditions[0]]: conditions[1] } : conditions;
@@ -668,7 +704,7 @@ Body row locator: ${this._bodyRowLocator.toString()}`
    * @see {@link getBodyCellLocatorByRowConditions} for finding specific cells by content
    */
   async getAllBodyCellLocatorsByHeaderName(header, options) {
-    const table = await this.getTable(options);
+    const table = await this.getTable(this.resolveTableOptionsForHeaderKeyMethods(options));
     const headers = this.mainHeaderRow(table.headerRows);
     const headerIndex = this.getHeaderIndex(header, headers);
     const locators = [];
@@ -740,17 +776,9 @@ Header row locator: ${this._headerRowLocator.toString()}`
    * });
    */
   async getJson(options) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
     const table = await this.getTable({
       bodyRowOptions: options == null ? void 0 : options.bodyRowOptions,
-      headerRowOptions: {
-        colspan: {
-          enabled: (_c = (_b = (_a = options == null ? void 0 : options.headerRowOptions) == null ? void 0 : _a.colspan) == null ? void 0 : _b.enabled) != null ? _c : true,
-          suffix: (_f = (_e = (_d = options == null ? void 0 : options.headerRowOptions) == null ? void 0 : _d.colspan) == null ? void 0 : _e.suffix) != null ? _f : true
-        },
-        duplicateSuffix: (_h = (_g = options == null ? void 0 : options.headerRowOptions) == null ? void 0 : _g.duplicateSuffix) != null ? _h : true,
-        emptyCellReplacement: (_j = (_i = options == null ? void 0 : options.headerRowOptions) == null ? void 0 : _i.emptyCellReplacement) != null ? _j : true
-      }
+      headerRowOptions: this.resolveHeaderRowOptionsForJsonKeys(options == null ? void 0 : options.headerRowOptions)
     });
     const headers = this.mainHeaderRow(table.headerRows);
     return table.bodyRows.map((row) => {
@@ -926,7 +954,7 @@ Body row locator: ${this._bodyRowLocator.toString()}`
    */
   async getDistinctColumnValues(headerName, options) {
     var _a;
-    const table = await this.getTable(options);
+    const table = await this.getTable(this.resolveTableOptionsForHeaderKeyMethods(options));
     const mainHeader = this.mainHeaderRow(table.headerRows);
     const headerIndex = this.getHeaderIndex(headerName, mainHeader);
     const values = /* @__PURE__ */ new Set();
@@ -964,10 +992,7 @@ Body row locator: ${this._bodyRowLocator.toString()}`
    */
   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 table = await this.getTable(this.resolveTableOptionsForHeaderKeyMethods(options));
     const mainHeader = this.mainHeaderRow(table.headerRows);
     const headerIndices = /* @__PURE__ */ new Map();
     for (const header of Object.keys(conditions)) {
@@ -1011,6 +1036,54 @@ Table locator: ${this._tableLocator.toString()}`
     }
     return { headerRows, bodyRows };
   }
+  normalizeGetBodyRowsOptions(options) {
+    if (!options) {
+      return {};
+    }
+    if (options.bodyRowOptions || options.headerRowOptions) {
+      return options;
+    }
+    if (options.cellContentType !== void 0) {
+      return {
+        bodyRowOptions: {
+          cellContentType: options.cellContentType
+        }
+      };
+    }
+    return options;
+  }
+  resolveHeaderRowOptionsForJsonKeys(headerOptions) {
+    return this.resolveHeaderRowOptions(headerOptions, {
+      defaultColspanEnabled: true,
+      defaultColspanSuffix: true,
+      defaultDuplicateSuffix: true,
+      defaultEmptyCellReplacement: true,
+      defaultNormalizeWhitespace: false,
+      defaultStripIconGlyphs: false
+    });
+  }
+  resolveTableOptionsForHeaderKeyMethods(options) {
+    const tableOptions = this.normalizeGetBodyRowsOptions(options);
+    return {
+      bodyRowOptions: tableOptions.bodyRowOptions,
+      headerRowOptions: this.resolveHeaderRowOptionsForJsonKeys(tableOptions.headerRowOptions)
+    };
+  }
+  resolveHeaderRowOptions(headerOptions, defaults) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const resolvedColspanEnabled = (defaults == null ? void 0 : defaults.forceColspanEnabled) ? true : (_b = (_a = headerOptions == null ? void 0 : headerOptions.colspan) == null ? void 0 : _a.enabled) != null ? _b : defaults == null ? void 0 : defaults.defaultColspanEnabled;
+    return {
+      cellContentType: headerOptions == null ? void 0 : headerOptions.cellContentType,
+      emptyCellReplacement: (_c = headerOptions == null ? void 0 : headerOptions.emptyCellReplacement) != null ? _c : defaults == null ? void 0 : defaults.defaultEmptyCellReplacement,
+      duplicateSuffix: (_d = headerOptions == null ? void 0 : headerOptions.duplicateSuffix) != null ? _d : defaults == null ? void 0 : defaults.defaultDuplicateSuffix,
+      normalizeWhitespace: (_e = headerOptions == null ? void 0 : headerOptions.normalizeWhitespace) != null ? _e : defaults == null ? void 0 : defaults.defaultNormalizeWhitespace,
+      stripIconGlyphs: (_f = headerOptions == null ? void 0 : headerOptions.stripIconGlyphs) != null ? _f : defaults == null ? void 0 : defaults.defaultStripIconGlyphs,
+      colspan: {
+        enabled: resolvedColspanEnabled,
+        suffix: (_h = (_g = headerOptions == null ? void 0 : headerOptions.colspan) == null ? void 0 : _g.suffix) != null ? _h : defaults == null ? void 0 : defaults.defaultColspanSuffix
+      }
+    };
+  }
   mainHeaderRow(headers) {
     var _a, _b, _c;
     if (headers.length === 0) {