chore: Add doc-string, make enableColumnFiltering toggerable

Author: NathanZlion

pages/table/grouped-columns-feat-combination.page.tsx

@@ -709,6 +709,7 @@ type DemoContext = React.Context<
     empty: boolean;
     cellVerticalAlign: string;
     sortingDisabled: boolean;
+    enableColumnFiltering: boolean;
   }>
 >;
 
@@ -736,6 +737,7 @@ export default function GroupedColumnsBugBash() {
       empty = false,
       cellVerticalAlign = 'middle',
       sortingDisabled = false,
+      enableColumnFiltering = true,
     },
     setUrlParams,
   } = useContext(AppContext as DemoContext);
@@ -941,6 +943,12 @@ export default function GroupedColumnsBugBash() {
             >
               RTL
             </Toggle>
+            <Toggle
+              checked={enableColumnFiltering}
+              onChange={({ detail }) => setUrlParams({ enableColumnFiltering: detail.checked })}
+            >
+              Column filtering
+            </Toggle>
           </SpaceBetween>
         </SpaceBetween>
 
@@ -1011,6 +1019,10 @@ export default function GroupedColumnsBugBash() {
             preferences={
               <CollectionPreferences
                 {...collectionPreferencesProps}
+                contentDisplayPreference={{
+                  ...collectionPreferencesProps.contentDisplayPreference!,
+                  enableColumnFiltering,
+                }}
                 preferences={preferences}
                 onConfirm={({ detail }) => setPreferences(detail)}
               />

src/test-utils/dom/collection-preferences/content-display-preference.ts

@@ -45,8 +45,15 @@ export class ContentDisplayOptionWrapper extends ComponentWrapper {
    *
    * The children are the leaf-level `ContentDisplayOptionWrapper`s inside the group's
    * nested `InternalList` — i.e. they already carry a drag handle and visibility toggle.
+   *
+   * @param option.group When `true`, returns only group items. When `false`, returns only leaf column items.
+   *   When omitted, returns all child items regardless of type.
    */
-  findChildrenOptions(): Array<ContentDisplayOptionWrapper> | null {
+  findChildrenOptions(
+    option: {
+      group?: boolean;
+    } = {}
+  ): Array<ContentDisplayOptionWrapper> | null {
     // Group items wrap their content in <div data-item-type="group">.
     // If that wrapper is absent this is a leaf column.
     const groupWrapper = this.getListItem().findContent().find('[data-item-type="group"]');
@@ -58,9 +65,20 @@ export class ContentDisplayOptionWrapper extends ComponentWrapper {
     if (!nestedList) {
       return null;
     }
-    return new ListWrapper(nestedList.getElement())
-      .findItems()
-      .map(item => new ContentDisplayOptionWrapper(item.getElement()));
+    const list = new ListWrapper(nestedList.getElement());
+
+    if (option.group === true) {
+      return list
+        .findAll(`li:has([data-item-type="group"])`)
+        .map(item => new ContentDisplayOptionWrapper(item.getElement()));
+    }
+    if (option.group === false) {
+      return list
+        .findAll(`li:has([data-item-type="column"])`)
+        .map(item => new ContentDisplayOptionWrapper(item.getElement()));
+    }
+
+    return list.findItems().map(item => new ContentDisplayOptionWrapper(item.getElement()));
   }
 }
 

src/test-utils/dom/table/index.ts

@@ -30,6 +30,9 @@ export default class TableWrapper extends ComponentWrapper {
     return this.findByClassName(styles['thead-active'])!;
   }
 
+  /**
+   * Returns the header slot of the table.
+   */
   findHeaderSlot(): ElementWrapper | null {
     return this.findByClassName(styles['header-controls']);
   }
@@ -42,70 +45,68 @@ export default class TableWrapper extends ComponentWrapper {
     return this.findHeaderSlot();
   }
 
+  /**
+   * Returns the footer slot of the table.
+   */
   findFooterSlot(): ElementWrapper | null {
     return this.containerWrapper.findFooter();
   }
 
   /**
-   * Returns all column header cells in the last header row (leaf columns).
-   * For tables without column grouping this is equivalent to querying `tr > *`.
+   * Returns column header cells from the table's header region.
+   *
+   * By default, returns all cells in the last header row (leaf columns).
+   * For tables without column grouping this is equivalent to querying all `<th>` elements.
    * For tables with column grouping this returns only the leaf-level column headers,
    * not the group header cells above them.
    *
-   * Pass `{ level }` to target a specific header row (1-based). Level 1 is the
-   * topmost row (group headers); the last level is always the leaf-column row.
-   *
-   * Pass `{ groupId }` to return only the leaf column headers that are direct
-   * children of the specified group. This uses the `data-column-group-id` attribute
-   * set on each leaf `<th>` by the renderer.
+   * Both `level` and `groupId` can be combined to narrow the result set.
    *
-   * @param option.level 1-based index of the header row to query. Defaults to the last row.
+   * @param option.level 1-based index of the header row to query. Level 1 is the topmost row
+   *   (group headers); the last level is always the leaf-column row. Defaults to the last row.
    * @param option.groupId ID of the parent group whose direct child columns to return.
+   *   Uses the `data-column-group-id` attribute set on each leaf `<th>` by the renderer.
    */
   findColumnHeaders(
     option: {
       groupId?: string;
       level?: number;
     } = {}
   ): Array<ElementWrapper> {
-    if (option.groupId !== undefined) {
-      return this.findActiveTHead().findAll(`tr:last-child > th[data-column-group-id="${option.groupId}"]`);
+    const { groupId, level } = option;
+    const parts: string[] = [];
+
+    // Row selector
+    if (level !== undefined) {
+      parts.push(`tr:nth-child(${level}) > `);
+    } else if (groupId === undefined) {
+      parts.push('tr:last-child > ');
     }
-    if (option.level !== undefined) {
-      return this.findActiveTHead().findAll(`tr:nth-child(${option.level}) > *`);
+
+    // Element selector
+    if (groupId !== undefined) {
+      parts.push(`th[data-column-group-id="${groupId}"]`);
+    } else {
+      parts.push('*');
     }
-    return this.findActiveTHead().findAll('tr:last-child > *');
+
+    return this.findActiveTHead().findAll(parts.join(''));
   }
 
   /**
-   * Returns the element the user clicks when resizing a column or group header.
-   * Targets the leaf-column header row by default.
+   * Returns the element the user clicks when resizing a column.
    *
-   * Pass `{ level }` to target a specific header row (1-based).
+   * Targets leaf-column headers (`scope="col"`), which reliably identifies
+   * individual columns regardless of which `<tr>` they appear in. In grouped
+   * tables, leaf columns may span multiple rows and sit in an earlier `<tr>`
+   * rather than the last one.
    *
-   * Pass `{ groupId }` to return the resizer of the group header cell with that ID.
-   * When `groupId` is provided, `columnIndex` is ignored.
-   *
-   * @param columnIndex 1-based index of the column containing the resizer (ignored when groupId is set).
-   * @param option.level 1-based index of the header row to query. Defaults to the last row.
-   * @param option.groupId ID of the group header whose resizer to return.
+   * @param columnIndex 1-based index of the leaf column containing the resizer.
    */
-  findColumnResizer(
-    columnIndex: number,
-    option: {
-      groupId?: string;
-      level?: number;
-    } = {}
-  ): ElementWrapper | null {
-    if (option.groupId !== undefined) {
-      // Use a CSS :has() selector to locate the colgroup <th> containing the group focus marker,
-      // then find the resizer inside it.
-      return this.findActiveTHead().find(
-        `th[scope="colgroup"]:has([data-focus-id="group-header-${option.groupId}"]) .${resizerStyles.resizer}`
-      );
-    }
-    const rowSelector = option.level !== undefined ? `tr:nth-child(${option.level})` : 'tr:last-child';
-    return this.findActiveTHead().find(`${rowSelector} th:nth-child(${columnIndex}) .${resizerStyles.resizer}`);
+  findColumnResizer(columnIndex: number): ElementWrapper | null {
+    const leafHeaders = this.findActiveTHead().findAll('th[scope="col"]');
+    const header = leafHeaders[columnIndex - 1];
+    return header?.find(`.${resizerStyles.resizer}`) ?? null;
   }
 
   /**
@@ -130,10 +131,16 @@ export default class TableWrapper extends ComponentWrapper {
     return this.findBodyCell(rowIndex, columnIndex)?.find(`.${testUtilStyles['body-cell-counter']}`) ?? null;
   }
 
+  /**
+   * Returns all table rows within the table body.
+   */
   findRows(): Array<ElementWrapper> {
     return this.findNativeTable().findAllByClassName(styles.row);
   }
 
+  /**
+   * Returns all selected table rows.
+   */
   findSelectedRows(): Array<ElementWrapper> {
     return this.findAllByClassName(styles['row-selected']);
   }
@@ -146,10 +153,16 @@ export default class TableWrapper extends ComponentWrapper {
     return this.findEmptySlot();
   }
 
+  /**
+   * Returns the empty state slot of the table.
+   */
   findEmptySlot(): ElementWrapper | null {
     return this.findByClassName(styles.empty);
   }
 
+  /**
+   * Returns the loading text element of the table.
+   */
   findLoadingText(): ElementWrapper | null {
     return this.findByClassName(styles.loading);
   }
@@ -187,26 +200,44 @@ export default class TableWrapper extends ComponentWrapper {
     return this.findNativeTable().find(`tbody tr:nth-child(${rowIndex}) .${selectionStyles.root}`);
   }
 
+  /**
+   * Returns the "select all" checkbox or radio button in the table header.
+   */
   findSelectAllTrigger(): ElementWrapper | null {
     return this.findActiveTHead().find(`.${selectionStyles.root}`);
   }
 
+  /**
+   * Returns the text filter component used in the table.
+   */
   findTextFilter(): TextFilterWrapper | null {
     return this.findComponent(`.${styles['tools-filtering']}`, TextFilterWrapper);
   }
 
+  /**
+   * Returns the property filter component used in the table.
+   */
   findPropertyFilter(): PropertyFilterWrapper | null {
     return this.findComponent(`.${styles['tools-filtering']}`, PropertyFilterWrapper);
   }
 
+  /**
+   * Returns the filter slot of the table.
+   */
   findFilterSlot(): ElementWrapper | null {
     return this.findComponent(`.${styles['tools-filtering']}`, ElementWrapper);
   }
 
+  /**
+   * Returns the collection preferences component used in the table.
+   */
   findCollectionPreferences(): CollectionPreferencesWrapper | null {
     return this.findComponent(`.${styles['tools-preferences']}`, CollectionPreferencesWrapper);
   }
 
+  /**
+   * Returns the pagination component used in the table.
+   */
   findPagination(): PaginationWrapper | null {
     return this.findComponent(`.${styles['tools-pagination']}`, PaginationWrapper);
   }
@@ -221,6 +252,9 @@ export default class TableWrapper extends ComponentWrapper {
     return this.findBodyCell(rowIndex, columnIndex)?.findByClassName(bodyCellStyles['body-cell-editor']) ?? null;
   }
 
+  /**
+   * Returns the currently active inline editing cell.
+   */
   findEditingCell(): ElementWrapper | null {
     return this.findNativeTable().findByClassName(bodyCellStyles['body-cell-edit-active']);
   }
@@ -229,10 +263,16 @@ export default class TableWrapper extends ComponentWrapper {
     return this.findEditingCell()?.findByClassName(bodyCellStyles['body-cell-editor-controls']) ?? null;
   }
 
+  /**
+   * Returns the save button of the currently active inline editing cell.
+   */
   findEditingCellSaveButton(): ElementWrapper | null {
     return this._findEditingCellControls()?.find('button[type="submit"]') ?? null;
   }
 
+  /**
+   * Returns the cancel button of the currently active inline editing cell.
+   */
   findEditingCellCancelButton(): ElementWrapper | null {
     return this._findEditingCellControls()?.find('button:first-child') ?? null;
   }