@thinkwise/testwise 0.2.62 → 0.2.99

package/components/BaseComponentObjects.ts

@@ -1,6 +1,23 @@
 import type { Locator, Page } from '@playwright/test';
 import type { IComponentObjects } from '../interfaces/IComponentObjects.js';
 
+/**
+ * Abstract base class for every `*Objects` locator class in `components/` and
+ * `controls/`.
+ *
+ * **What it does:** Sets up two universal locators that every component needs:
+ * - `context` — the scoped root `Locator` passed in from the component. All
+ *   descendant locator lookups are chained from this, so the component only
+ *   sees elements within its own section of the page.
+ * - `mainHeader` — a `main header` locator used as a presence anchor to
+ *   confirm the screen is fully rendered before asserting.
+ *
+ * **For contributors:** When adding a new component, create
+ * `<Name>Objects.ts` that extends this class. Put ALL selector logic (every
+ * `getByTestId`, `locator`, `getByRole`, etc.) in the `Objects` class. The
+ * companion `<Name>.ts` should only contain interaction logic and must never
+ * contain raw locator strings.
+ */
 export abstract class BaseComponentObjects implements IComponentObjects {
   context: Locator;
   mainHeader: Locator;

package/components/action-bar/ActionBar.ts

@@ -1,6 +1,11 @@
 import type { Locator, Page } from '@playwright/test';
 import { ActionBarObjects, ActionBarOverflowableObjects } from './ActionBarObjects.js';
 
+/**
+ * Internal helper used by `ActionBar` to group and expose action button
+ * interactions. Handles overflow menus where actions are hidden behind a
+ * "more" button.
+ */
 class ActionBarActions {
   private _objects: ActionBarOverflowableObjects;
 
@@ -84,66 +89,49 @@ class ActionBarActions {
   public getCubeViewButtons = (): Locator => this._objects.cubeViewButtons();
   public getCubeViewButtonById = (id: string): Locator => this._objects.cubeViewButtonById(id);
   public getCubeViewButtonByLabel = (label: string): Locator => this._objects.cubeViewButtonByLabel(label);
+
+  // Generic item lookup for ids not covered by the typed getters above
+  public getItemByTestId = (testId: string): Locator => this._objects.itemByTestId(testId);
 }
 
+/**
+ * Wraps the Thinkwise action-bar toolbar that sits above a grid or form and
+ * contains buttons for CRUD operations (New, Edit, Save, Delete, Refresh)
+ * plus any custom task actions defined in the Thinkwise model.
+ *
+ * In generated subject classes this is exposed as a typed `actionBar` property.
+ * Overflow actions (hidden under a "more" button) are accessible via `actionBar.overflowMenu`.
+ *
+ * @example
+ * await subject.actionBar.getButtonByText('New').click();
+ * await subject.actionBar.getButtonByText('Save').click();
+ * // For overflow actions:
+ * await subject.actionBar.overflowMenu.getButtonByText('Export').click();
+ */
 export class ActionBar extends ActionBarActions {
   private _actionBarObjects: ActionBarObjects;
-  private _overflowMenu: ActionBarOverflow;
+  public overflowMenu: ActionBarActions;
 
   constructor(actionBarContext: Locator) {
     super(actionBarContext);
     this._actionBarObjects = new ActionBarObjects(actionBarContext.page(), actionBarContext);
-    this._overflowMenu = new ActionBarOverflow(actionBarContext.page());
+
+    const overflowInstance = new ActionBarOverflow(actionBarContext.page());
+    this.overflowMenu = new Proxy(overflowInstance, {
+      get: (target, prop, receiver) => {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value === 'function') {
+          return (...args: unknown[]) =>
+            wrapWithOverflowOpen(this, () => (value as (...args: unknown[]) => Locator).apply(target, args));
+        }
+        return value;
+      }
+    }) as ActionBarActions;
   }
 
   public openOverflowMenu = async (): Promise<void> => {
     await this._actionBarObjects.overflowMenuButton().click();
   };
-
-  overflowMenu = {
-    getFilterButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getFilterButton()),
-
-    getQuickFilterButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getQuickFilterButton()),
-
-    getClearAllFiltersButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getClearAllFiltersButton()),
-
-    getSortButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getSortButton()),
-
-    getRestoreSortOrderButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getRestoreSortOrderButton()),
-
-    getImportButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getImportButton()),
-
-    getExportButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getExportButton()),
-
-    getExportImmediatelyButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getExportImmediatelyButton()),
-
-    getMassUpdateButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getMassUpdateButton()),
-
-    getUpScreenTypeButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getUpScreenTypeButton()),
-
-    getUpDetailSettingsButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getUpDetailSettingsButton()),
-
-    getUpManagePrefiltersButton: () =>
-      wrapWithOverflowOpen(this, () => this._overflowMenu.getUpManagePrefiltersButton()),
-
-    getUpGridSettingsButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getUpGridSettingsButton()),
-
-    getCubeSortButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getCubeSortButton()),
-
-    getCubePivotSettingsButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getCubePivotSettingsButton()),
-
-    getCubeChartSettingsButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getCubeChartSettingsButton()),
-
-    getExportPivotButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getExportPivotButton()),
-
-    getDeleteCubeViewButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getDeleteCubeViewButton()),
-
-    getSaveAsCubeViewButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getSaveAsCubeViewButton()),
-
-    getCollapseAllButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getCollapseAllButton()),
-
-    getExpandAllButton: () => wrapWithOverflowOpen(this, () => this._overflowMenu.getExpandAllButton())
-  };
 }
 
 export class ActionBarOverflow extends ActionBarActions {

package/components/action-bar/ActionBarObjects.ts

@@ -97,6 +97,8 @@ export class ActionBarOverflowableObjects extends BaseComponentObjects {
   // Prefilter buttons: data-testid like: "prefilter-actionbar-group-other__<something>"
   public prefilterButtonById = (id: string) =>
     this.context.getByTestId(new RegExp(`^prefilter-actionbar-group-${id}$`));
+
+  public itemByTestId = (testId: string) => this.context.getByTestId(testId);
 }
 
 export class ActionBarObjects extends ActionBarOverflowableObjects {

package/components/action-bar/CustomActionBar.ts

@@ -1,5 +1,11 @@
 import { ActionBar } from './ActionBar.js';
 
+/**
+ * Extension point for a customised action bar that behaves identically to
+ * `ActionBar` but can be subclassed to add subject-specific button helpers.
+ * Used in generated subject classes when the pipeline detects a custom action
+ * bar configuration.
+ */
 export class CustomActionBar extends ActionBar {
   // What should this do differently?
 }

package/components/cardlist/Cardlist.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { CardlistObjects } from './CardlistObjects.js';
 
+/**
+ * Wraps the Thinkwise card-list component that displays data as a grid of
+ * visual cards instead of a traditional table.
+ *
+ * In generated subject classes this is exposed as a typed `cardlist` property.
+ */
 export class Cardlist {
   cardlistObjects: CardlistObjects;
 

package/components/chart/Chart.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { ChartObjects } from './ChartObjects.js';
 
+/**
+ * Wraps the Thinkwise chart component that renders data as bar, line, or pie
+ * charts within a subject screen.
+ *
+ * In generated subject classes this is exposed as a typed `chart` property.
+ */
 export class Chart {
   chartObjects: ChartObjects;
 

package/components/combined-filter/CombinedFilter.ts

@@ -1,6 +1,15 @@
 import type { Locator } from '@playwright/test';
 import { CombinedFilterObjects } from './CombinedFIlterObjects.js';
 
+/**
+ * Wraps the Thinkwise combined-filter component that merges the filter form
+ * and prefilter list into a single collapsible panel alongside a grid.
+ *
+ * In generated subject classes this is exposed as a typed `combinedFilter` property.
+ *
+ * @example
+ * await subject.combinedFilter.context.waitFor({ state: 'visible' });
+ */
 export class CombinedFilter {
   combinedFilterObjects: CombinedFilterObjects;
 

package/components/cube-view-bar/CubeViewBar.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { CubeViewBarObjects } from './CubeViewBarObjects.js';
 
+/**
+ * Wraps the Thinkwise cube-view-bar component that provides navigation and
+ * filter controls for OLAP cube / pivot analysis screens.
+ *
+ * In generated subject classes this is exposed as a typed `cubeViewBar` property.
+ */
 export class CubeViewBar {
   cubeViewBarObjects: CubeViewBarObjects;
 

package/components/export/ExportComponent.ts

@@ -5,6 +5,18 @@ import { ExportComponentObjects } from './ExportComponentObjects.js';
 
 // ToDo: Expand on the selectColumns to select by columnId/testId, or what makes sense to empower the end-user
 // ToDo: Make changes to  completeExport be able to parse based on the data type selected
+/**
+ * Drives the Thinkwise data-export panel: choose rows (all or selected),
+ * select columns, pick a format (CSV, XLSX, XLS), download, and optionally
+ * parse the downloaded CSV back into a JavaScript array for assertions.
+ *
+ * Access via `page.components.export` — no need to construct this yourself.
+ *
+ * @example
+ * await page.components.export.exportAllRows();
+ * await page.components.export.selectFormat(ExportFormat.XLSX);
+ * await page.components.export.completeExport();
+ */
 export class ExportComponent {
   private _page: Page;
   private _objects: ExportComponentObjects;

package/components/filter/ExcelStyleFilterPopup.ts

@@ -1,28 +1,101 @@
 import type { Locator, Page } from '@playwright/test';
 import { ExcelStyleFilterPopupObjects } from './ExcelStyleFilterPopupObjects.js';
 
+/**
+ * Wraps the Excel-style column filter popup in a Thinkwise grid.
+ * This popup opens when a user right-clicks a column header and allows
+ * filtering by selecting individual cell values, much like Excel's auto-filter.
+ *
+ * Used internally by `GridColumnControl.filterByColumnValueExcelStyle()`.
+ *
+ * @example
+ * // Via GridColumnControl (preferred):
+ * await subject.grid.statusColumn.filterByColumnValueExcelStyle('Active');
+ */
 export class ExcelStyleFilterPopup {
-  private _excelStyleFilterPopupObjects: ExcelStyleFilterPopupObjects;
+  private _objects: ExcelStyleFilterPopupObjects;
 
   constructor(page: Page) {
-    this._excelStyleFilterPopupObjects = new ExcelStyleFilterPopupObjects(page);
+    this._objects = new ExcelStyleFilterPopupObjects(page);
   }
 
-  async waitForOpen(): Promise<void> {
-    await this._excelStyleFilterPopupObjects.anchor().waitFor({ state: 'visible' });
+  public async waitForOpen(): Promise<void> {
+    await (await this._objects.popup().all()).filter(async (element) => await element.isVisible());
   }
 
-  intervalFilters(): Locator {
-    return this._excelStyleFilterPopupObjects.intervalFilters();
+  public intervalFilters(): Locator {
+    return this._objects.intervalFilters();
   }
 
-  fromDateInput(fieldTestId: string): Locator {
-    return this._excelStyleFilterPopupObjects.fromDateInput(fieldTestId);
+  public fromDateInput(fieldTestId: string): Locator {
+    return this._objects.fromDateInput(fieldTestId);
   }
 
-  async setFromDate(fieldTestId: string, value: string): Promise<void> {
+  public toDateInput(fieldTestId: string): Locator {
+    return this._objects.toDateInput(fieldTestId);
+  }
+
+  public async waitForClose(): Promise<void> {
+    await (await this._objects.popup().all()).filter(async (element) => !(await element.isVisible()));
+  }
+
+  public async clickSelectAll(fieldTestId: string): Promise<void> {
+    await this.waitForOpen();
+    await this._objects.checkboxSelectAllButton(fieldTestId).click();
+  }
+
+  public async deselectAll(fieldTestId: string): Promise<void> {
+    const selectAllCheckbox = await this._objects.checkboxSelectAllButton(fieldTestId);
+    await this.waitForOpen();
+
+    // Everything is already deselected
+    if ((await selectAllCheckbox.locator('[data-testid="CheckBoxOutlineBlankIcon"]').count()) > 0) {
+      return;
+    }
+
+    // Some things are selected - first click will select everything
+    if ((await selectAllCheckbox.locator('[data-testid="CheckBoxIndeterminateIcon"]').count()) > 0) {
+      await selectAllCheckbox.click();
+    }
+
+    // Everything is selected
+    if ((await selectAllCheckbox.locator('[data-testid="CheckBoxIcon"]').count()) > 0) {
+      await selectAllCheckbox.click();
+    }
+  }
+
+  public async clickCheckboxItem(fieldTestId: string, value: string): Promise<void> {
+    await this.waitForOpen();
+
+    await this._objects.checkboxItemButtons(fieldTestId).filter({ hasText: value }).click();
+  }
+
+  public checkboxItem(fieldTestId: string, value: string): Locator {
+    return this._objects.checkboxItemCheckboxes(fieldTestId).filter({ hasText: value });
+  }
+
+  public fromTimeInput(fieldTestId: string): Locator {
+    return this._objects.fromTimeInput(fieldTestId);
+  }
+
+  public toTimeInput(fieldTestId: string): Locator {
+    return this._objects.toTimeInput(fieldTestId);
+  }
+
+  public setFromTime = async (fieldTestId: string, value: string): Promise<void> =>
+    this.fillAndEnter(fieldTestId, value);
+
+  public setToTime = async (fieldTestId: string, value: string): Promise<void> => this.fillAndEnter(fieldTestId, value);
+
+  public setFromDate = async (fieldTestId: string, value: string): Promise<void> =>
+    this.fillAndEnter(fieldTestId, value);
+
+  public setToDate = async (fieldTestId: string, value: string): Promise<void> => this.fillAndEnter(fieldTestId, value);
+
+  private async fillAndEnter(fieldTestId: string, value: string): Promise<void> {
+    const input = this._objects.fromDateInput(fieldTestId);
+
     await this.waitForOpen();
-    const input = this._excelStyleFilterPopupObjects.fromDateInput(fieldTestId);
     await input.fill(value);
     await input.press('Enter');
   }

package/components/filter/ExcelStyleFilterPopupObjects.ts

@@ -5,11 +5,10 @@ export class ExcelStyleFilterPopupObjects extends BaseComponentObjects {
   private _page: Page;
 
   constructor(page: Page) {
-    super(page, page.locator('body'));
+    super(page);
     this._page = page;
   }
-
-  public anchor = () => this._page.locator('[data-testid^="date-time-excel-filter__"]').first();
+  public popup = () => this._page.locator('[data-testid*="-excel-filter__"]');
 
   public intervalFilters = () => this._page.getByTestId('excel-style-filter-popup__interval-filters');
 
@@ -17,4 +16,31 @@ export class ExcelStyleFilterPopupObjects extends BaseComponentObjects {
     this._page
       .getByTestId(`date-time-excel-filter__${fieldTestId}__from`)
       .getByTestId(`form-field__${fieldTestId}__date__input`);
+
+  public toDateInput = (fieldTestId: string) =>
+    this._page
+      .getByTestId(`date-time-excel-filter__${fieldTestId}__to`)
+      .getByTestId(`form-field__${fieldTestId}__date__input`);
+
+  public checkboxList = (fieldTestId: string) =>
+    this._page.locator(`[data-testid*="-excel-filter__${fieldTestId}__list"]`);
+
+  public checkboxSelectAllButton = (fieldTestId: string) =>
+    this._page.locator(`[data-testid*="-excel-filter__${fieldTestId}__list-item-select-all-checkbox"]`);
+
+  public checkboxItemButtons = (fieldTestId: string) =>
+    this._page.locator(`[data-testid*="-excel-filter__${fieldTestId}__list-item-button__"]`);
+
+  public checkboxItemCheckboxes = (fieldTestId: string) =>
+    this._page.locator(`[data-testid*="-excel-filter__${fieldTestId}__list-item-checkbox__"]`);
+
+  public fromTimeInput = (fieldTestId: string) =>
+    this._page
+      .getByTestId(`date-time-excel-filter__${fieldTestId}__from`)
+      .getByTestId(`form-field__${fieldTestId}__time__input`);
+
+  public toTimeInput = (fieldTestId: string) =>
+    this._page
+      .getByTestId(`date-time-excel-filter__${fieldTestId}__to`)
+      .getByTestId(`form-field__${fieldTestId}__time__input`);
 }

package/components/filter/FilterForm.ts

@@ -1,6 +1,16 @@
 import type { Locator } from '@playwright/test';
 import { FilterFormObjects } from './FilterFormObjects.js';
 
+/**
+ * Wraps the Thinkwise filter form that appears in the filter panel alongside
+ * a grid. Provides access to the filter form's context locator for scoped
+ * assertions and interactions.
+ *
+ * In generated subject classes this is exposed as a typed component property.
+ *
+ * @example
+ * await subject.filterForm.context.waitFor({ state: 'visible' });
+ */
 export class FilterForm {
   filterFormObjects: FilterFormObjects;
 

package/components/filter/FilterPopup.ts

@@ -2,6 +2,19 @@ import type { Locator, Page } from '@playwright/test';
 import { PopUpComponent } from '../pop-up/PopUpComponent.js';
 import { FilterPopupObjects } from './FilterPopupObjects.js';
 
+/**
+ * Wraps the Thinkwise interval/range filter popup that appears when filtering
+ * date, time, or numeric columns with a "between" style filter.
+ *
+ * Extends `PopUpComponent` so all base popup actions (confirm, cancel) work
+ * here too. The `IntervalType` union type controls which date/time variant
+ * of the popup is targeted.
+ *
+ * @example
+ * // Open the filter popup, set a date range, and confirm:
+ * await subject.grid.hireDateColumn.openExcelStyleFilterPopup();
+ * // Then interact with the resulting FilterPopup instance.
+ */
 export type IntervalType =
   | 'date'
   | 'date-and-time'
@@ -93,6 +106,10 @@ export class FilterPopup {
     return this._filterPopupObjects.fieldInput(fieldId);
   }
 
+  public fieldInputChip(fieldId: string, value: string): Locator {
+    return this._filterPopupObjects.fieldInputChip(fieldId, value);
+  }
+
   public valueInput(fieldId: string, part: string): Locator {
     return this._filterPopupObjects.valueInput(fieldId, part);
   }
@@ -138,21 +155,25 @@ export class FilterPopup {
     await this._filterPopupObjects.timeOperatorControl().click();
   }
 
-  public intervalSelector(rowIndex: number, colId: string): Locator {
-    return this._filterPopupObjects.intervalSelector(rowIndex, colId);
+  public intervalSelector(colId: string): Locator {
+    return this._filterPopupObjects.intervalSelector(colId);
   }
 
-  public intervalSelectorInput(rowIndex: number, colId: string): Locator {
-    return this._filterPopupObjects.intervalSelectorInput(rowIndex, colId);
+  public intervalSelectorInput(colId: string): Locator {
+    return this._filterPopupObjects.intervalSelectorInput(colId);
   }
 
-  public async openInterval(rowIndex: number, colId: string): Promise<void> {
+  public async openInterval(colId: string, options?: { rowIndex?: number }): Promise<void> {
     await this.waitForOpen();
-    await this._filterPopupObjects.intervalSelectorInput(rowIndex, colId).click();
+    if (options?.rowIndex !== undefined) {
+      await this._filterPopupObjects.intervalSelectorInputByRowIndex(options.rowIndex, colId).click();
+    } else {
+      await this._filterPopupObjects.intervalSelectorInput(colId).click();
+    }
   }
 
-  public async setInterval(rowIndex: number, colId: string, kind: IntervalType): Promise<void> {
-    await this.openInterval(rowIndex, colId);
+  public async setInterval(colId: string, kind: IntervalType, options?: { rowIndex?: number }): Promise<void> {
+    await this.openInterval(colId, options);
     await this.pickAutocomplete(kind);
   }
 
@@ -170,7 +191,7 @@ export class FilterPopup {
     const emptyRow = this._filterPopupObjects.emptySelectFieldRow();
 
     if (await emptyRow.count()) {
-      await this._filterPopupObjects.emptySelectFieldRowButton().click();
+      await this._filterPopupObjects.emptySelectFieldRowButton().press('Enter');
     } else {
       await this._filterPopupObjects.selectFieldButton().click();
     }

package/components/filter/FilterPopupObjects.ts

@@ -23,6 +23,9 @@ export class FilterPopupObjects extends BaseComponentObjects {
 
   public fieldInput = (fieldId: string) => this.context.getByTestId(`form-field__${fieldId}__input`);
 
+  public fieldInputChip = (fieldId: string, value: string) =>
+    this.context.getByTestId(`form-field__${fieldId}__input`).getByTestId(`autocomplete-tag-${value}`);
+
   public prefilterNameInput = () => this.context.getByTestId('prefilter__name__input');
 
   public saveAsOption = () => this._page.getByRole('menuitem', { name: 'Save' });
@@ -43,11 +46,15 @@ export class FilterPopupObjects extends BaseComponentObjects {
   public timeOperatorControl = () =>
     this.context.getByTestId('form-field__event-time__operator__control').getByRole('button', { name: 'Open' });
 
-  public intervalSelector = (rowIndex: number, colId: string) =>
+  public intervalSelector = (colId: string) => this.context.locator(`[data-testid$="__${colId}__select-interval"]`);
+
+  public intervalSelectorInput = (colId: string) => this.intervalSelector(colId).getByTestId('select-interval__input');
+
+  public intervalSelectorByRowIndex = (rowIndex: number, colId: string) =>
     this.context.getByTestId(`advanced-filter-grid__row${rowIndex}__${colId}__select-interval`);
 
-  public intervalSelectorInput = (rowIndex: number, colId: string) =>
-    this.intervalSelector(rowIndex, colId).getByTestId('select-interval__input');
+  public intervalSelectorInputByRowIndex = (rowIndex: number, colId: string) =>
+    this.intervalSelectorByRowIndex(rowIndex, colId).getByTestId('select-interval__input');
 
   public autocompleteOption = (key: AutocompleteKey) => this._page.getByTestId(`autocomplete-option-${key}`);
 

package/components/filter/FindForm.ts

@@ -1,3 +1,10 @@
+/**
+ * Placeholder for the Thinkwise "Find" form — a search dialog used to
+ * quickly locate records by keyword across multiple fields.
+ *
+ * This component is under development. Check back for typed interaction
+ * helpers in a future release.
+ */
 export class FindForm {
   // do stuff
 }

package/components/filter/ManagePrefilterPopup.ts

@@ -2,6 +2,17 @@ import type { Locator, Page } from '@playwright/test';
 import { PopUpComponent } from '../pop-up/PopUpComponent.js';
 import { ManagePrefilterPopupObjects } from './ManagePrefilterPopupObjects.js';
 
+/**
+ * Wraps the Thinkwise "Manage Prefilter" popup that lets users create, edit,
+ * and delete personal prefilters from within a running test.
+ *
+ * Access via `page.components.managePrefilterPopup` — no need to construct
+ * this yourself. Extends `PopUpComponent` so all base popup methods are also
+ * available.
+ *
+ * @example
+ * await page.components.managePrefilterPopup.dialog().waitFor({ state: 'visible' });
+ */
 export class ManagePrefilterPopup extends PopUpComponent {
   private readonly _page: Page;
   private _managePrefilterPopupObjects: ManagePrefilterPopupObjects;

package/components/form/Form.ts

@@ -1,6 +1,22 @@
 import type { Locator } from '@playwright/test';
 import { FormObjects } from './FormObjects.js';
 
+/**
+ * Wraps a Thinkwise form screen component. Provides locator helpers for
+ * finding fields by value and by column ID.
+ *
+ * In generated subject classes, you interact with `Form` indirectly through
+ * the typed `Components/` class (e.g. `EmployeeFormComponent`) which exposes
+ * named, typed control properties. Use `Form` directly only when you need
+ * raw field lookups not covered by the generated accessors.
+ *
+ * @example
+ * // Via generated subject (preferred):
+ * await subject.form.firstNameField.fill('Jane');
+ *
+ * // Via raw Form helper:
+ * const field = subject.form.getFieldByColId('first_name');
+ */
 export class Form {
   private _objects: FormObjects;