@vuu-ui/vuu-playwright-helpers 3.5.14 → 3.5.16

package/README.md

@@ -41,8 +41,16 @@ The existing `locateCell` overloads remain available for gradual migration.
 const menu = await table.showContextMenu("ric", 2);
 
 expect(await menu.hasMenuItems()).toBe(true);
-expect(await menu.hasMenuItems(["Copy text", "Filter"])).toBe(true); // exact, in order
-expect(await menu.menuItemLabels()).toEqual(["Copy text", "Filter"]);
+// exact match, in order - a partial list is false
+expect(
+  await menu.hasMenuItems(["Copy text", "Filter", "Sort", "Delete row"]),
+).toBe(true);
+expect(await menu.menuItemLabels()).toEqual([
+  "Copy text",
+  "Filter",
+  "Sort",
+  "Delete row",
+]);
 
 const copy = menu.menuItem("Copy text"); // or by 0 based index, menu.menuItem(0)
 expect(await copy.hasIcon("edit")).toBe(true);
@@ -61,6 +69,46 @@ await menu.press("Enter");
 await menu.close(); // Escape
 ```
 
+To assert that right clicking a cell does not show a context menu, use
+`assertNoContextMenu`. It waits for the page to render after the right click
+before asserting, so it cannot pass before a menu would have appeared.
+
+```ts
+await table.assertNoContextMenu("ccy", 2);
+```
+
 When a key press depends on the focus change made by the previous key, call
 `assertFocusedMenuItem` in between. Keys pressed before the menu has processed a
 focus change may be delivered to the previously focused item.
+
+## PwChart, PwChartDataPoint
+
+`PwChart` wraps a Vuu `Chart` (ECharts, svg renderer). Data points are located by
+series name (the Vuu column name) and 0 based data index, or category (x axis)
+value, mirroring `PwTable.cell(colName, ariaRowIndex)`.
+
+```ts
+const chart = await new PwChart(page).isReady();
+expect(await chart.seriesNames()).toEqual(["price", "volume"]);
+expect(await chart.categories()).toHaveLength(25);
+
+const point = await chart.dataPoint("price", 3); // or chart.dataPoint("price", "2026-04-05")
+expect(point.value).toEqual(103);
+expect(point.isExcluded).toBe(false);
+await point.hover();
+await point.click(); // selects, with a chart selectionModel
+await expect(point.symbol).toHaveAttribute("fill", "purple");
+
+const menu = await chart.showContextMenu("price", 3); // or point.showContextMenu()
+await menu.menuItem("Exclude Item").click();
+await chart.assertNoContextMenu("price", 3); // when no menu is configured
+```
+
+The data point properties (`value`, `x`, `y`, `isExcluded`) are a snapshot, taken
+when the data point is obtained. Mouse actions resolve the position again and wait
+until it is stable, so they work while the chart is resizing. To assert a change to
+the data, obtain the data point again, e.g.
+`await expect.poll(async () => (await chart.dataPoint("price", 3)).isExcluded).toBe(true)`.
+
+The Vuu `Chart` exposes its ECharts instance on the chart canvas element
+(`echartsInstance`), which `PwChart` uses to map data points to pixel positions.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.14",
+  "version": "3.5.16",
   "author": "heswell",
   "license": "Apache-2.0",
   "main": "./src/index.js",
@@ -9,7 +9,7 @@
     "type-defs": "node ../../scripts/build-type-defs.mjs"
   },
   "dependencies": {
-    "@vuu-ui/vuu-protocol-types": "3.5.14"
+    "@vuu-ui/vuu-protocol-types": "3.5.16"
   },
   "peerDependencies": {
     "@playwright/test": "^1.62.1"

package/src/PwChart.js

@@ -0,0 +1,77 @@
+import { expect } from "@playwright/test";
+import { PwComponent } from "./PwComponent.js";
+import { PwContextMenu } from "./PwContextMenu.js";
+import { PwChartDataPoint } from "./PwChartDataPoint.js";
+class PwChart extends PwComponent {
+    defaultCssSelector = ".vuuChart";
+    get canvas() {
+        return this.locator.locator("[_echarts_instance_]");
+    }
+    async isReady(options) {
+        await super.isReady(options);
+        await expect.poll(()=>this.canvas.evaluate((element)=>(element.echartsInstance?.getOption().series ?? []).some((series)=>series.data.length > 0)), options).toBe(true);
+        return this;
+    }
+    async seriesNames() {
+        await this.isReady();
+        return this.canvas.evaluate((element)=>{
+            const series = element.echartsInstance?.getOption().series ?? [];
+            return Array.from(new Set(series.map(({ name })=>name)));
+        });
+    }
+    async categories() {
+        await this.isReady();
+        return this.canvas.evaluate((element)=>element.echartsInstance?.getOption().xAxis?.[0]?.data ?? []);
+    }
+    async dataPoint(seriesName, dataIndexOrCategory) {
+        await this.isReady();
+        const resolve = ()=>this.resolveDataPoint(seriesName, dataIndexOrCategory);
+        return new PwChartDataPoint(this.page, this.canvas, await resolve(), resolve);
+    }
+    async resolveDataPoint(seriesName, dataIndexOrCategory) {
+        const info = await this.canvas.evaluate((element, [seriesName, dataIndexOrCategory])=>{
+            const chart = element.echartsInstance;
+            if (!chart) return "chart has no echartsInstance";
+            const { series = [], xAxis = [] } = chart.getOption();
+            const categories = xAxis[0]?.data ?? [];
+            const dataIndex = "number" == typeof dataIndexOrCategory ? dataIndexOrCategory : categories.indexOf(dataIndexOrCategory);
+            if (-1 === dataIndex) return `no category "${dataIndexOrCategory}"`;
+            const namedSeries = series.filter(({ name })=>name === seriesName);
+            if (0 === namedSeries.length) return `no series "${seriesName}"`;
+            const valueSeries = namedSeries.find(({ data })=>"number" == typeof data[dataIndex]?.value);
+            if (!valueSeries) return `series "${seriesName}" has no value at data index ${dataIndex}`;
+            const value = valueSeries.data[dataIndex].value;
+            const [x, y] = chart.convertToPixel({
+                seriesId: valueSeries.id
+            }, [
+                dataIndex,
+                value
+            ]);
+            return {
+                seriesName,
+                dataIndex,
+                category: categories[dataIndex],
+                value,
+                isExcluded: valueSeries.id !== seriesName,
+                x,
+                y
+            };
+        }, [
+            seriesName,
+            dataIndexOrCategory
+        ]);
+        if ("string" == typeof info) throw Error(`PwChart, dataPoint, ${info}`);
+        return info;
+    }
+    async showContextMenu(seriesName, dataIndexOrCategory) {
+        const dataPoint = await this.dataPoint(seriesName, dataIndexOrCategory);
+        return dataPoint.showContextMenu();
+    }
+    async assertNoContextMenu(seriesName, dataIndexOrCategory) {
+        const dataPoint = await this.dataPoint(seriesName, dataIndexOrCategory);
+        await PwContextMenu.assertNotOpened(this.page, ()=>dataPoint.click({
+                button: "right"
+            }));
+    }
+}
+export { PwChart };

package/src/PwChartDataPoint.js

@@ -0,0 +1,61 @@
+import { PlaywrightPageObject } from "./PlaywrightPageObject.js";
+import { PwContextMenu } from "./PwContextMenu.js";
+class PwChartDataPoint extends PlaywrightPageObject {
+    canvas;
+    resolve;
+    seriesName;
+    dataIndex;
+    category;
+    value;
+    isExcluded;
+    x;
+    y;
+    constructor(page, canvas, info, resolve){
+        super(page), this.canvas = canvas, this.resolve = resolve;
+        this.seriesName = info.seriesName;
+        this.dataIndex = info.dataIndex;
+        this.category = info.category;
+        this.value = info.value;
+        this.isExcluded = info.isExcluded;
+        this.x = info.x;
+        this.y = info.y;
+    }
+    get symbol() {
+        const position = `,${round(this.x)},${round(this.y)})`;
+        return this.canvas.locator(`svg path[transform$="${position}"]`);
+    }
+    async click(options) {
+        const position = await this.stablePosition();
+        await this.canvas.click({
+            ...options,
+            position
+        });
+    }
+    async hover() {
+        await this.canvas.hover({
+            position: await this.stablePosition()
+        });
+    }
+    showContextMenu() {
+        return PwContextMenu.open(this.page, ()=>this.click({
+                button: "right"
+            }));
+    }
+    async stablePosition() {
+        let { x, y } = await this.resolve();
+        for(let attempt = 0; attempt < MAX_STABLE_ATTEMPTS; attempt++){
+            await nextAnimationFrames(this.page);
+            const current = await this.resolve();
+            if (current.x === x && current.y === y) return {
+                x,
+                y
+            };
+            ({ x, y } = current);
+        }
+        throw Error(`PwChartDataPoint, ${this.seriesName}[${this.dataIndex}] position is not stable`);
+    }
+}
+const MAX_STABLE_ATTEMPTS = 50;
+const round = (value)=>parseFloat(value.toFixed(4));
+const nextAnimationFrames = (page)=>page.evaluate(()=>new Promise((resolve)=>requestAnimationFrame(()=>requestAnimationFrame(()=>resolve()))));
+export { PwChartDataPoint };

package/src/PwContextMenu.js

@@ -1,8 +1,22 @@
 import { expect } from "@playwright/test";
 import { PwComponent } from "./PwComponent.js";
 import { PwMenuItem } from "./PwMenuItem.js";
+import { byId } from "./selector-utils.js";
 class PwContextMenu extends PwComponent {
     defaultCssSelector = '.vuuContextMenuPanel[role="menu"]';
+    static async open(page, openAction) {
+        await openAction();
+        const menu = await new PwContextMenu(page).isReady();
+        const menuId = await menu.locator.getAttribute("id");
+        const contextMenu = menuId ? new PwContextMenu(page, byId(menuId)) : menu;
+        await expect(contextMenu.locator.and(page.locator(":focus-within"))).toHaveCount(1);
+        return contextMenu;
+    }
+    static async assertNotOpened(page, openAction) {
+        await openAction();
+        await page.evaluate(()=>new Promise((resolve)=>requestAnimationFrame(()=>requestAnimationFrame(()=>resolve()))));
+        await new PwContextMenu(page).assertNotAttached();
+    }
     get menuItems() {
         return this.locator.getByRole("menuitem");
     }

package/src/PwTable.js

@@ -2,7 +2,7 @@ import { expect } from "@playwright/test";
 import { PwComponent } from "./PwComponent.js";
 import { PwContextMenu } from "./PwContextMenu.js";
 import { PwTableHeaderCell } from "./PwTableHeaderCell.js";
-import { byDataIcon, byId, cssAttributeValue } from "./selector-utils.js";
+import { byDataIcon, cssAttributeValue } from "./selector-utils.js";
 const byAriaRowIndex = (ariaRowIndex)=>`[aria-rowindex="${ariaRowIndex}"]:scope`;
 const xpathStringLiteral = (value)=>{
     if (!value.includes("'")) return `'${value}'`;
@@ -53,12 +53,16 @@ class PwTable extends PwComponent {
     }
     async showContextMenu(columnName, ariaRowIndex) {
         const cell = await this.cell(columnName, ariaRowIndex);
-        await cell.click({
-            button: "right"
-        });
-        const menu = await new PwContextMenu(this.page).isReady();
-        const menuId = await menu.locator.getAttribute("id");
-        return menuId ? new PwContextMenu(this.page, byId(menuId)) : menu;
+        return PwContextMenu.open(this.page, ()=>cell.click({
+                button: "right"
+            }));
+    }
+    async assertNoContextMenu(columnName, ariaRowIndex) {
+        const cell = await this.cell(columnName, ariaRowIndex);
+        await PwContextMenu.assertNotOpened(this.page, ()=>cell.click({
+                button: "right"
+            }));
+        await expect(cell).not.toContainClass("ContextOpen");
     }
     locateCell(rowOrText, column) {
         if ("number" == typeof rowOrText && "number" == typeof column) return this.locator.locator(`[aria-rowindex="${rowOrText}"] > [aria-colindex="${column}"]`);

package/src/index.js

@@ -1,4 +1,6 @@
 export { PlaywrightPageObject } from "./PlaywrightPageObject.js";
+export { PwChart } from "./PwChart.js";
+export { PwChartDataPoint } from "./PwChartDataPoint.js";
 export { PwComponent } from "./PwComponent.js";
 export { PwContextMenu } from "./PwContextMenu.js";
 export { PwMenuItem } from "./PwMenuItem.js";

package/types/PwChart.d.ts

@@ -0,0 +1,124 @@
+import { type Locator } from "@playwright/test";
+import { PwComponent } from "./PwComponent";
+import { PwContextMenu } from "./PwContextMenu";
+import { PwChartDataPoint } from "./PwChartDataPoint";
+/**
+ * A Vuu Chart (VuuChart, an ECharts line chart). Data points are identified by
+ * series name, which is the Vuu column name, and 0 based data index, which is
+ * also the index of the category on the x axis.
+ *
+ * The chart must use the svg renderer for symbol locators (PwChartDataPoint.symbol).
+ *
+ * @example
+ * test("chart renders price and volume", async ({ mount, page }) => {
+ *   await mount("Chart/LineChart/SimpleLineChart");
+ *   const chart = await new PwChart(page).isReady();
+ *   expect(await chart.seriesNames()).toEqual(["price", "volume"]);
+ *   const point = await chart.dataPoint("price", 0);
+ *   expect(point.value).toEqual(100);
+ * });
+ */
+export declare class PwChart extends PwComponent {
+    protected readonly defaultCssSelector = ".vuuChart";
+    /**
+     * Locator for the element that renders the chart. This element receives
+     * mouse events and holds the ECharts instance.
+     *
+     * @example
+     * test("chart renders svg", async ({ page }) => {
+     *   const chart = new PwChart(page);
+     *   await expect(chart.canvas.locator("svg")).toBeVisible();
+     * });
+     */
+    get canvas(): Locator;
+    /**
+     * Wait until the chart is visible and has rendered series data. Resolves
+     * with the chart, so it can be chained.
+     *
+     * @example
+     * test("chart is ready", async ({ mount, page }) => {
+     *   await mount("Chart/LineChart/SimpleLineChart");
+     *   const chart = await new PwChart(page).isReady();
+     *   expect(await chart.categories()).toHaveLength(25);
+     * });
+     */
+    isReady(options?: {
+        timeout?: number;
+    }): Promise<this>;
+    /**
+     * The names of the rendered series, in render order. These are the Vuu
+     * column names of the series columns.
+     *
+     * @example
+     * test("price only", async ({ page }) => {
+     *   await page.getByRole("button", { name: "Price Only" }).click();
+     *   const chart = await new PwChart(page).isReady();
+     *   await expect.poll(() => chart.seriesNames()).toEqual(["price"]);
+     * });
+     */
+    seriesNames(): Promise<string[]>;
+    /**
+     * The category (x axis) values, in order.
+     *
+     * @example
+     * test("first category", async ({ page }) => {
+     *   const chart = await new PwChart(page).isReady();
+     *   expect((await chart.categories())[0]).toEqual("2026-04-02");
+     * });
+     */
+    categories(): Promise<string[]>;
+    /**
+     * Locate a data point by series name and 0 based data index, or by category
+     * (x axis) value. Waits for the chart to be ready. Rejects if the series or
+     * data point does not exist, or the data point has no value.
+     *
+     * @param seriesName the series (Vuu column) name
+     * @param dataIndexOrCategory 0 based data index, or category value
+     *
+     * @example
+     * test("locate data points", async ({ page }) => {
+     *   const chart = new PwChart(page);
+     *   const byIndex = await chart.dataPoint("price", 3);
+     *   const byCategory = await chart.dataPoint("price", "2026-04-05");
+     *   expect(byIndex.value).toEqual(byCategory.value);
+     * });
+     */
+    dataPoint(seriesName: string, dataIndexOrCategory: number | string): Promise<PwChartDataPoint>;
+    private resolveDataPoint;
+    /**
+     * Right click a data point to invoke the context menu. Resolves once the
+     * menu is visible and has focus. Waits until the test timeout if no context
+     * menu is shown, use assertNoContextMenu to test for that.
+     *
+     * @param seriesName the series (Vuu column) name
+     * @param dataIndexOrCategory 0 based data index, or category value
+     *
+     * @example
+     * test("exclude data point", async ({ mount, page }) => {
+     *   await mount("Chart/LineChart/DataExclusions");
+     *   const chart = new PwChart(page);
+     *   const menu = await chart.showContextMenu("price", 3);
+     *   expect(await menu.hasMenuItems(["Exclude Item"])).toBe(true);
+     *   await menu.menuItem("Exclude Item").click();
+     *   await expect
+     *     .poll(async () => (await chart.dataPoint("price", 3)).isExcluded)
+     *     .toBe(true);
+     * });
+     */
+    showContextMenu(seriesName: string, dataIndexOrCategory: number | string): Promise<PwContextMenu>;
+    /**
+     * Right click a data point and assert that no context menu is shown. Waits
+     * for the page to render after the right click before asserting, so it
+     * cannot pass before a menu would have appeared.
+     *
+     * @param seriesName the series (Vuu column) name
+     * @param dataIndexOrCategory 0 based data index, or category value
+     *
+     * @example
+     * test("no context menu in view mode", async ({ mount, page }) => {
+     *   await mount("Chart/LineChart/EditableChart");
+     *   await new PwChart(page).assertNoContextMenu("price", 3);
+     * });
+     */
+    assertNoContextMenu(seriesName: string, dataIndexOrCategory: number | string): Promise<void>;
+}

package/types/PwChartDataPoint.d.ts

@@ -0,0 +1,116 @@
+import type { Locator, Page } from "@playwright/test";
+import { PlaywrightPageObject } from "./PlaywrightPageObject";
+import { PwContextMenu } from "./PwContextMenu";
+/**
+ * Position and value of a chart data point, as resolved by PwChart.
+ */
+export interface ChartDataPointInfo {
+    seriesName: string;
+    /**
+     * 0 based index into the series data (and the category axis).
+     */
+    dataIndex: number;
+    /**
+     * The category (x axis) value at dataIndex.
+     */
+    category: string;
+    value: number;
+    /**
+     * True when the data point is rendered as an excluded data item.
+     */
+    isExcluded: boolean;
+    /**
+     * Pixel position of the data point, relative to the chart canvas.
+     */
+    x: number;
+    y: number;
+}
+/**
+ * A single data point within a PwChart. Obtained from PwChart.dataPoint.
+ *
+ * The properties (value, x, y etc) are a snapshot, taken when the data point is
+ * obtained. Interactions (click, hover, right click) are performed with the
+ * mouse at the data point's current position, which is resolved again before
+ * each action, waiting until the position is stable (e.g. while the chart is
+ * resizing). This mirrors Playwright Locator actionability checks.
+ *
+ * @example
+ * test("select a data point", async ({ page }) => {
+ *   const chart = new PwChart(page);
+ *   const point = await chart.dataPoint("price", 3);
+ *   expect(point.value).toEqual(103);
+ *   await point.click();
+ *   await expect(point.symbol).toHaveAttribute("fill", "purple");
+ * });
+ */
+export declare class PwChartDataPoint extends PlaywrightPageObject implements ChartDataPointInfo {
+    private readonly canvas;
+    private readonly resolve;
+    readonly seriesName: string;
+    readonly dataIndex: number;
+    readonly category: string;
+    readonly value: number;
+    readonly isExcluded: boolean;
+    readonly x: number;
+    readonly y: number;
+    /**
+     * @param page the Playwright page
+     * @param canvas Locator for the element that renders the chart (and receives mouse events)
+     * @param info position and value of the data point
+     * @param resolve resolves the current position and value of the data point
+     */
+    constructor(page: Page, canvas: Locator, info: ChartDataPointInfo, resolve: () => Promise<ChartDataPointInfo>);
+    /**
+     * Locator for the symbol rendered at this data point (an SVG path, requires
+     * the svg renderer). Matched by position only, so its size and color can be
+     * asserted as they change, e.g. on hover or selection. Uses the position
+     * when the data point was obtained.
+     *
+     * @example
+     * test("hover enlarges symbol", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   await expect(point.symbol).toBeAttached();
+     *   await point.hover();
+     *   await expect(point.symbol).toHaveAttribute("transform", /^matrix\(8,/);
+     * });
+     */
+    get symbol(): Locator;
+    /**
+     * Click the data point. With a chart selectionModel, this toggles selection.
+     *
+     * @example
+     * test("click selects data point", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   await point.click();
+     *   await expect(point.symbol).toHaveAttribute("fill", "purple");
+     * });
+     */
+    click(options?: Omit<Parameters<Locator["click"]>[0], "position">): Promise<void>;
+    /**
+     * Move the mouse over the data point.
+     *
+     * @example
+     * test("hover highlights data point", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   await point.hover();
+     *   await expect(point.symbol).toHaveAttribute("transform", /^matrix\(8,/);
+     * });
+     */
+    hover(): Promise<void>;
+    /**
+     * Right click the data point to invoke the context menu. Resolves once the
+     * menu is visible and has focus.
+     *
+     * @example
+     * test("exclude data point", async ({ page }) => {
+     *   const point = await new PwChart(page).dataPoint("price", 3);
+     *   const menu = await point.showContextMenu();
+     *   await menu.menuItem("Exclude Item").click();
+     * });
+     */
+    showContextMenu(): Promise<PwContextMenu>;
+    /**
+     * The current position of the data point, once it has stopped moving.
+     */
+    private stablePosition;
+}

package/types/PwComponent.d.ts

@@ -9,6 +9,18 @@ export type PwComponentTarget = string | Locator;
  * Base class for helpers that wrap a single component instance. Subclasses
  * provide a defaultCssSelector, which can be overridden at runtime by passing
  * a css selector or Locator to the constructor.
+ *
+ * @example
+ * // a hypothetical helper for a toolbar component
+ * export class PwToolbar extends PwComponent {
+ *   protected readonly defaultCssSelector = ".vuuToolbar";
+ * }
+ *
+ * test("toolbar renders", async ({ page }) => {
+ *   await new PwToolbar(page).assertVisible();
+ *   await new PwToolbar(page, "#main-toolbar").assertVisible();
+ *   await new PwToolbar(page, page.getByTestId("toolbar")).assertVisible();
+ * });
  */
 export declare abstract class PwComponent extends PlaywrightPageObject {
     protected readonly target?: PwComponentTarget | undefined;
@@ -21,6 +33,12 @@ export declare abstract class PwComponent extends PlaywrightPageObject {
     /**
      * Locator for the component root element. Use this for web-first assertions
      * that are not covered by a helper method.
+     *
+     * @example
+     * test("menu is vertical", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await expect(menu.locator).toHaveAttribute("aria-orientation", "vertical");
+     * });
      */
     get locator(): Locator;
     /**
@@ -36,8 +54,35 @@ export declare abstract class PwComponent extends PlaywrightPageObject {
     /**
      * Is the component currently visible. Does not wait or retry, prefer
      * assertVisible within tests unless the component is known to be stable.
+     *
+     * @example
+     * test("menu is open", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.isVisible()).toBe(true);
+     * });
      */
     isVisible(): Promise<boolean>;
+    /**
+     * Assert the component is visible, retrying until the expect timeout.
+     *
+     * @example
+     * test("table renders", async ({ mount, page }) => {
+     *   await mount("Table/ContextMenu/LocalContextMenu");
+     *   await new PwTable(page).assertVisible();
+     * });
+     */
     assertVisible(): Promise<void>;
+    /**
+     * Assert the component is not in the DOM, retrying until the expect timeout.
+     * Passes as soon as the element is absent, so it does not prove an element
+     * will not appear later (see PwTable.assertNoContextMenu).
+     *
+     * @example
+     * test("menu closes after click", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Copy text").click();
+     *   await menu.assertNotAttached();
+     * });
+     */
     assertNotAttached(): Promise<void>;
 }

package/types/PwContextMenu.d.ts

@@ -1,4 +1,4 @@
-import { type Locator } from "@playwright/test";
+import { type Locator, type Page } from "@playwright/test";
 import { PwComponent } from "./PwComponent";
 import { PwMenuItem } from "./PwMenuItem";
 /**
@@ -9,7 +9,9 @@ import { PwMenuItem } from "./PwMenuItem";
  * test("cell menu", async ({ page }) => {
  *   const table = new PwTable(page);
  *   const menu = await table.showContextMenu("ric", 2);
- *   expect(await menu.hasMenuItems(["Copy text", "Filter"])).toBe(true);
+ *   expect(
+ *     await menu.hasMenuItems(["Copy text", "Filter", "Sort", "Delete row"]),
+ *   ).toBe(true);
  *   const filterMenu = await menu.menuItem("Filter").openSubMenu();
  *   await filterMenu.menuItem("Include value").click();
  *   await menu.assertNotAttached();
@@ -17,33 +19,129 @@ import { PwMenuItem } from "./PwMenuItem";
  */
 export declare class PwContextMenu extends PwComponent {
     protected readonly defaultCssSelector = ".vuuContextMenuPanel[role=\"menu\"]";
+    /**
+     * Perform the action that opens a context menu (e.g. a right click), then
+     * resolve with the menu once it is visible and has focus. Component helpers
+     * use this to implement showContextMenu.
+     *
+     * @example
+     * test("context menu from custom element", async ({ page }) => {
+     *   const menu = await PwContextMenu.open(page, () =>
+     *     page.getByTestId("panel").click({ button: "right" }),
+     *   );
+     *   expect(await menu.hasMenuItems()).toBe(true);
+     * });
+     */
+    static open(page: Page, openAction: () => Promise<unknown>): Promise<PwContextMenu>;
+    /**
+     * Perform the action that would open a context menu (e.g. a right click),
+     * then assert that no context menu is shown.
+     *
+     * A negative assertion passes as soon as the menu is absent, which may be
+     * before a menu would have rendered. To avoid false passes we wait for two
+     * animation frames after the action, allowing React to commit and the menu
+     * to be positioned, before asserting.
+     *
+     * @example
+     * test("no context menu on panel", async ({ page }) => {
+     *   await PwContextMenu.assertNotOpened(page, () =>
+     *     page.getByTestId("panel").click({ button: "right" }),
+     *   );
+     * });
+     */
+    static assertNotOpened(page: Page, openAction: () => Promise<unknown>): Promise<void>;
     /**
      * Locator for the menu items of this menu. Sub menus are rendered in their
      * own (portalled) panels, so their items are not included.
+     *
+     * @example
+     * test("menu has four items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await expect(menu.menuItems).toHaveCount(4);
+     * });
      */
     get menuItems(): Locator;
     /**
      * The labels of the menu items, in rendered order.
+     *
+     * @example
+     * test("menu items are in expected order", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItemLabels()).toEqual([
+     *     "Copy text",
+     *     "Filter",
+     *     "Sort",
+     *     "Delete row",
+     *   ]);
+     * });
      */
     menuItemLabels(): Promise<string[]>;
     /**
      * With no argument, does the menu have any menu items. With labels, does
-     * the menu have exactly these menu items, in this order.
+     * the menu have exactly these menu items, in this order. Labels are compared
+     * exactly, a partial list returns false.
+     *
+     * Does not wait or retry. The menu items are rendered with the menu, so this
+     * is safe to call once the menu is ready (e.g. after showContextMenu).
+     *
+     * @example
+     * test("cell menu has expected items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.hasMenuItems()).toBe(true);
+     *   expect(
+     *     await menu.hasMenuItems(["Copy text", "Filter", "Sort", "Delete row"]),
+     *   ).toBe(true);
+     *   // exact match, a partial list is false
+     *   expect(await menu.hasMenuItems(["Copy text", "Filter"])).toBe(false);
+     * });
+     *
+     * @example
+     * test("sub menu has expected items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filterMenu = await menu.menuItem("Filter").openSubMenu();
+     *   expect(
+     *     await filterMenu.hasMenuItems(["Include value", "Exclude value"]),
+     *   ).toBe(true);
+     * });
      */
     hasMenuItems(labels?: string[]): Promise<boolean>;
     /**
-     * Menu item by label, or by 0 based index.
+     * Menu item by label (exact match), or by 0 based index.
+     *
+     * @example
+     * test("locate menu items", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const copy = menu.menuItem("Copy text");
+     *   expect(await copy.isEnabled()).toBe(true);
+     *   expect(await menu.menuItem(1).label()).toEqual("Filter");
+     * });
      */
     menuItem(labelOrIndex: string | number): PwMenuItem;
     /**
      * The menu item that currently has keyboard focus. The item must also be the
      * menu's active item (tabindex="0"), which confirms the menu has processed the
      * focus change and is ready for the next key press.
+     *
+     * @example
+     * test("first item focused after ArrowDown", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await expect(menu.focusedMenuItem.locator).toHaveText("Copy text");
+     * });
      */
     get focusedMenuItem(): PwMenuItem;
     /**
      * Assert the focused menu item. Wait on this between key presses, keys
      * pressed before the menu has processed a focus change may be misdirected.
+     *
+     * @example
+     * test("arrow keys move focus", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Copy text");
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Filter");
+     * });
      */
     assertFocusedMenuItem(label: string): Promise<void>;
     /**
@@ -53,13 +151,23 @@ export declare class PwContextMenu extends PwComponent {
      * a key depends on the focus change of the previous key.
      *
      * @example
-     * await menu.press("ArrowDown");
-     * await menu.assertFocusedMenuItem("Filter");
-     * await menu.press("Enter");
+     * test("Enter invokes focused item", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Copy text");
+     *   await menu.press("Enter");
+     *   await menu.assertNotAttached();
+     * });
      */
     press(...keys: string[]): Promise<void>;
     /**
-     * Close the menu by pressing Escape.
+     * Close the menu by pressing Escape. Resolves once the menu is removed.
+     *
+     * @example
+     * test("Escape closes menu", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.close();
+     * });
      */
     close(): Promise<void>;
 }

package/types/PwMenuItem.d.ts

@@ -4,45 +4,193 @@ import { PwContextMenu } from "./PwContextMenu";
 /**
  * A single item within a PwContextMenu. Usually obtained from
  * PwContextMenu.menuItem rather than constructed directly.
+ *
+ * The boolean query methods (hasChildren, isDisabled, hasIcon etc) read the
+ * current state and do not retry. For state that changes after an action, use
+ * a web-first assertion on `locator`, e.g.
+ * `await expect(item.locator).toHaveAttribute("aria-expanded", "true")`.
+ *
+ * @example
+ * test("menu item state", async ({ page }) => {
+ *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+ *   const item = menu.menuItem("Copy text");
+ *   expect(await item.isEnabled()).toBe(true);
+ *   expect(await item.hasIcon("edit")).toBe(true);
+ *   await item.click();
+ * });
  */
 export declare class PwMenuItem extends PwComponent {
     protected readonly defaultCssSelector = "[role=\"menuitem\"]";
     /**
      * The text label of the menu item.
+     *
+     * @example
+     * test("second item is Filter", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem(1).label()).toEqual("Filter");
+     * });
      */
     label(): Promise<string>;
     /**
-     * Does this menu item open a sub menu.
+     * Does this menu item open a sub menu (aria-haspopup="menu").
+     *
+     * @example
+     * test("Filter has a sub menu", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Filter").hasChildren()).toBe(true);
+     *   expect(await menu.menuItem("Copy text").hasChildren()).toBe(false);
+     * });
      */
     hasChildren(): Promise<boolean>;
+    /**
+     * Is the menu item disabled (aria-disabled="true"). Disabled items cannot be
+     * clicked and are skipped by keyboard navigation.
+     *
+     * @example
+     * test("Delete row is disabled", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Delete row").isDisabled()).toBe(true);
+     * });
+     */
     isDisabled(): Promise<boolean>;
+    /**
+     * Is the menu item enabled. The inverse of isDisabled.
+     *
+     * @example
+     * test("Copy text is enabled", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Copy text").isEnabled()).toBe(true);
+     * });
+     */
     isEnabled(): Promise<boolean>;
     /**
-     * Is the sub menu of this menu item open. Always false for leaf items.
+     * Is the sub menu of this menu item open (aria-expanded="true"). Always
+     * false for leaf items.
+     *
+     * @example
+     * test("Filter expands on hover", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filter = menu.menuItem("Filter");
+     *   expect(await filter.isExpanded()).toBe(false);
+     *   await filter.openSubMenu();
+     *   expect(await filter.isExpanded()).toBe(true);
+     * });
      */
     isExpanded(): Promise<boolean>;
+    /**
+     * Does the menu item have DOM focus. Does not wait or retry, prefer
+     * PwContextMenu.assertFocusedMenuItem after a key press.
+     *
+     * @example
+     * test("Copy text focused", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.press("ArrowDown");
+     *   await menu.assertFocusedMenuItem("Copy text");
+     *   expect(await menu.menuItem("Copy text").isFocused()).toBe(true);
+     * });
+     */
     isFocused(): Promise<boolean>;
     /**
      * Is the menu item decorated with the given icon (data-icon attribute).
+     *
+     * @example
+     * test("Copy text has edit icon", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   expect(await menu.menuItem("Copy text").hasIcon("edit")).toBe(true);
+     * });
      */
     hasIcon(iconName: string): Promise<boolean>;
     /**
      * Click the menu item. Playwright will not click a disabled item unless
      * { force: true } is passed.
+     *
+     * @example
+     * test("click invokes menu action", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Copy text").click();
+     *   await menu.assertNotAttached();
+     * });
+     *
+     * @example
+     * test("clicking disabled item does nothing", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Delete row").click({ force: true });
+     *   await menu.assertVisible();
+     * });
      */
     click(options?: Parameters<Locator["click"]>[0]): Promise<void>;
+    /**
+     * Hover over the menu item. Hovering an item with children opens its sub
+     * menu, use openSubMenu to also wait for the sub menu.
+     *
+     * @example
+     * test("hover expands Filter", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filter = menu.menuItem("Filter");
+     *   await filter.hover();
+     *   await expect(filter.locator).toHaveAttribute("aria-expanded", "true");
+     * });
+     */
     hover(): Promise<void>;
+    /**
+     * Give the menu item DOM focus.
+     *
+     * @example
+     * test("focus Sort then open with keyboard", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const sort = menu.menuItem("Sort");
+     *   await sort.focus();
+     *   await sort.press("ArrowRight");
+     *   await expect(sort.locator).toHaveAttribute("aria-expanded", "true");
+     * });
+     */
     focus(): Promise<void>;
+    /**
+     * Press a key with the menu item as target. Focuses the item first.
+     *
+     * @example
+     * test("Enter on item invokes action", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   await menu.menuItem("Copy text").press("Enter");
+     *   await menu.assertNotAttached();
+     * });
+     */
     press(key: string): Promise<void>;
     /**
      * The sub menu opened by this menu item. The sub menu must already be open,
      * use openSubMenu to open it.
+     *
+     * @example
+     * test("sub menu opened by hover", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filter = menu.menuItem("Filter");
+     *   await filter.hover();
+     *   const filterMenu = await filter.subMenu();
+     *   expect(await filterMenu.hasMenuItems()).toBe(true);
+     * });
      */
     subMenu(): Promise<PwContextMenu>;
     /**
      * Open the sub menu of this menu item, using the mouse (hover) or keyboard
      * (ArrowRight). Resolves once the sub menu is visible and, when opened with
      * the keyboard, once focus has moved into the sub menu.
+     *
+     * @example
+     * test("open sub menu with mouse", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const filterMenu = await menu.menuItem("Filter").openSubMenu();
+     *   await filterMenu.menuItem("Include value").click();
+     *   await menu.assertNotAttached();
+     * });
+     *
+     * @example
+     * test("open sub menu with keyboard", async ({ page }) => {
+     *   const menu = await new PwTable(page).showContextMenu("ric", 2);
+     *   const sortMenu = await menu.menuItem("Sort").openSubMenu("keyboard");
+     *   await sortMenu.assertFocusedMenuItem("Ascending");
+     *   await sortMenu.press("ArrowLeft");
+     *   await sortMenu.assertNotAttached();
+     * });
      */
     openSubMenu(using?: "mouse" | "keyboard"): Promise<PwContextMenu>;
 }

package/types/PwTable.d.ts

@@ -4,18 +4,79 @@ import { PwComponent } from "./PwComponent";
 import { PwContextMenu } from "./PwContextMenu";
 import { PwTableHeaderCell } from "./PwTableHeaderCell";
 type AriaRole = "cell" | "textbox" | "combobox";
+/**
+ * A Vuu Table. Rows are located by 1-based aria row index, which includes
+ * header rows (with one header, the first data row is 2).
+ *
+ * @example
+ * test("table renders instruments", async ({ mount, page }) => {
+ *   await mount("Table/ContextMenu/LocalContextMenu");
+ *   const table = new PwTable(page);
+ *   await table.assertVisible();
+ *   await expect(await table.cell("ric", 2)).toHaveText("AAOO.L");
+ * });
+ */
 export declare class PwTable extends PwComponent {
     protected readonly defaultCssSelector = ".vuuTable";
+    /**
+     * Locator for the scrollable content container (the rendered rows).
+     *
+     * @example
+     * test("rows are zebra striped", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await expect(table.contentContainer).toContainClass("vuuTable-zebra");
+     * });
+     */
     get contentContainer(): Locator;
+    /**
+     * Locator for the scrollbar container, the element that scrolls.
+     *
+     * @example
+     * test("scrolls vertically", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollbarContainer.evaluate((el) => el.scrollTo(0, 1000));
+     *   await expect(table.row(2)).not.toBeInViewport();
+     * });
+     */
     get scrollbarContainer(): Locator;
     /**
-     * row Locator by aria-index
+     * Row Locator by 1-based aria row index, including headers.
+     *
+     * @example
+     * test("first data row is selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await (await table.cell("ric", 2)).click();
+     *   await expect(table.row(2)).toHaveAttribute("aria-selected", "true");
+     * });
      */
     row(row: number): Locator;
     /**
      * Locate cell by column name and 1-based aria row index, including headers.
+     * Preferred over locateCell for new usage.
+     *
+     * @example
+     * test("first ric", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await expect(await table.cell("ric", 2)).toHaveText("AAOO.L");
+     * });
      */
     cell(colName: string, ariaRowIndex: number): Promise<Locator>;
+    /**
+     * Double click a cell to edit it, fill the editor with value, then commit
+     * (Enter) or cancel (Escape) the edit.
+     *
+     * @example
+     * test("edit bbg", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstrumentsInlineEdit");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   const textbox = (await table.cell("bbg", 2)).getByRole("textbox");
+     *   await table.editCell("bbg", 2, "X", "cancel");
+     *   await expect(textbox).not.toHaveValue("X");
+     *   await table.editCell("bbg", 2, "X");
+     *   await expect(textbox).toHaveValue("X");
+     * });
+     */
     editCell(columnName: string, ariaRowIndex: number, value: string, action?: "commit" | "cancel"): Promise<void>;
     /**
      * The labels displayed in the column headers, in rendered order.
@@ -60,10 +121,21 @@ export declare class PwTable extends PwComponent {
      * });
      */
     cellsWithIcon(iconName: string): Locator;
+    /**
+     * The column header cell for the named column.
+     *
+     * @example
+     * test("currency column not selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   expect(await table.headerCell("currency").isSelected).toBe(false);
+     * });
+     */
     headerCell(columnName: string): PwTableHeaderCell;
     /**
      * Right click a cell to invoke the context menu. Resolves once the menu is
-     * visible. Rejects if no context menu is shown.
+     * visible and has focus, so keyboard navigation can begin immediately.
+     * Waits until the test timeout if no context menu is shown, use
+     * assertNoContextMenu to test for that.
      *
      * @param columnName name of the column
      * @param ariaRowIndex 1-based aria row index, including headers (with one header, the first data row is 2)
@@ -77,31 +149,174 @@ export declare class PwTable extends PwComponent {
      */
     showContextMenu(columnName: string, ariaRowIndex: number): Promise<PwContextMenu>;
     /**
-     * Locate cell by cell contents
-     * @param text
+     * Right click a cell and assert that no context menu is shown and the cell
+     * is not marked as having an open context menu.
+     *
+     * A negative assertion passes as soon as the menu is absent, which may be
+     * before a menu would have rendered. To avoid false passes we wait for two
+     * animation frames after the right click, allowing React to commit and the
+     * menu to be positioned, before asserting.
+     *
+     * @param columnName name of the column
+     * @param ariaRowIndex 1-based aria row index, including headers (with one header, the first data row is 2)
+     *
+     * @example
+     * test("no menu when none configured", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertNoContextMenu("ccy", 2);
+     * });
+     */
+    assertNoContextMenu(columnName: string, ariaRowIndex: number): Promise<void>;
+    /**
+     * Locate cell(s) by accessible name (cell contents). May match several cells.
+     *
+     * @example
+     * test("right click ric", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.locateCell("AAOP N").click({ button: "right" });
+     * });
      */
     locateCell(text: string): Locator;
     /**
-     * Locate cell by aria row index and aria col index
-     * @param text
+     * Locate cell by 1-based aria row index and 1-based aria col index.
+     *
+     * @example
+     * test("down arrow from header focuses first cell", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.locateColumnHeader(1).press("ArrowDown");
+     *   await expect(table.locateCell(2, 1)).toBeFocused();
+     * });
      */
     locateCell(row: number, column: number): Locator;
     /**
-     * Locate cell by aria row index and column name
+     * Locate cell by 1-based aria row index and column name. Prefer cell(columnName, ariaRowIndex).
+     *
+     * @example
+     * test("first ric", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await expect(await table.locateCell(2, "ric")).toHaveText("AAOO.L");
+     * });
      */
     locateCell(row: number, columnName: string): Promise<Locator>;
+    /**
+     * Locate a column header cell by 1-based aria col index.
+     *
+     * @example
+     * test("click header focuses it", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   const header = table.locateColumnHeader(1);
+     *   await header.click();
+     *   await expect(header).toBeFocused();
+     * });
+     */
     locateColumnHeader(column: number): Locator;
+    /**
+     * When isEditable is true, assert the cell is editable but not currently in
+     * edit mode and, if value is passed, that its textbox has that value. When
+     * isEditable is false or undefined, nothing is asserted.
+     *
+     * @example
+     * test("first cell is editable", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   await table.assertCellIsEditable(2, 1, true, "AAOO L");
+     * });
+     */
     assertCellIsEditable(row: number, column: number, isEditable: boolean | undefined, value?: string): Promise<void>;
     private getCellText;
+    /**
+     * Assert the value of a cell input (toHaveValue). Pass a role to target an
+     * element within the cell, e.g. "textbox" for an editable cell.
+     *
+     * @example
+     * test("editable cell value", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   await table.assertCellValue(2, 1, "AAOO L", "textbox");
+     *   await table.assertCellValue(table.locateCell(2, 1), "AAOO L", "textbox");
+     * });
+     */
     assertCellValue(cell: Locator, text: string, role?: AriaRole): Promise<void>;
     assertCellValue(row: number, column: number, text: string, role?: AriaRole): Promise<void>;
+    /**
+     * Assert the text content of a cell (toHaveText). Pass a role to target an
+     * element within the cell, e.g. "combobox" for a dropdown cell.
+     *
+     * @example
+     * test("first cell text", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertCellContent(2, 1, "AAOO L");
+     *   await table.assertCellContent(table.locateCell(2, 1), "AAOO L");
+     * });
+     */
     assertCellContent(cell: Locator, text: string, role?: AriaRole): Promise<void>;
     assertCellContent(row: number, column: number, text: string, role?: AriaRole): Promise<void>;
+    /**
+     * Assert a cell, or an element within it with the given role, is focused.
+     *
+     * @example
+     * test("click focuses editable cell", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   const cell = table.locateCell(3, 3);
+     *   await cell.click();
+     *   await table.assertCellIsFocused(cell, "textbox");
+     *   await table.assertCellIsFocused(3, 3, "textbox");
+     * });
+     */
     assertCellIsFocused(cell: Locator, role?: AriaRole): Promise<void>;
     assertCellIsFocused(row: number, column: number, role?: AriaRole): Promise<void>;
+    /**
+     * Assert a cell is (default) or is not in edit mode.
+     *
+     * @example
+     * test("Enter starts editing, Escape stops", async ({ mount, page }) => {
+     *   await mount("Table/Editing/EditableInstruments");
+     *   await page.getByRole("radio", { name: "Edit" }).click();
+     *   const table = new PwTable(page);
+     *   const cell = table.locateCell(3, 3);
+     *   await cell.click();
+     *   await cell.press("Enter");
+     *   await table.assertCellIsEditing(cell);
+     *   await cell.press("Escape");
+     *   await table.assertCellIsEditing(cell, false);
+     * });
+     */
     assertCellIsEditing(cell: Locator, isEditing?: boolean): Promise<void>;
     assertCellIsEditing(row: number, column: number, isEditing?: boolean): Promise<void>;
+    /**
+     * Assert which rows are rendered, given the visible range of data rows.
+     * Checks the rendered row count includes the leading and trailing buffers
+     * and that buffered rows beyond the viewport are not in view.
+     *
+     * @param range the visible range of (0-based) data rows
+     * @param renderBufferSize number of rows rendered beyond each end of the viewport
+     * @param totalRowCount size of the dataSource
+     * @param headerCount number of header rows, default 1
+     *
+     * @example
+     * test("initial render", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertRenderedRows({ from: 0, to: 30 }, 5, 1000);
+     * });
+     */
     assertRenderedRows({ from, to }: VuuRange, renderBufferSize: number, totalRowCount: number, headerCount?: number): Promise<void>;
+    /**
+     * Assert which columns are rendered and which are in the viewport, checked
+     * against the first data row. Ranges are inclusive, 1-based aria col indexes.
+     *
+     * @example
+     * test("column virtualization", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.assertRenderedColumns({
+     *     rendered: { from: 1, to: 8 },
+     *     visible: { from: 1, to: 6 },
+     *   });
+     * });
+     */
     assertRenderedColumns({ rendered, visible, }: {
         rendered: VuuRange;
         visible: VuuRange;

package/types/PwTableHeaderCell.d.ts

@@ -1,5 +1,14 @@
 import { type Page } from "@playwright/test";
 import { PwComponent, type PwComponentTarget } from "./PwComponent";
+/**
+ * A Table column header cell. Usually obtained from PwTable.headerCell.
+ *
+ * @example
+ * test("currency header", async ({ page }) => {
+ *   const header = new PwTable(page).headerCell("currency");
+ *   await expect(header.locator).toHaveText("Currency");
+ * });
+ */
 export declare class PwTableHeaderCell extends PwComponent {
     protected readonly defaultCssSelector = ".vuuTableHeaderCell";
     /**
@@ -7,6 +16,26 @@ export declare class PwTableHeaderCell extends PwComponent {
      * @param target css selector or Locator for the header cell
      */
     constructor(page: Page, target: PwComponentTarget);
+    /**
+     * Does the header cell have the selected class. Does not wait or retry,
+     * use assertSelected after an action that selects the column.
+     *
+     * @example
+     * test("no column initially selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   expect(await table.headerCell("currency").isSelected).toBe(false);
+     * });
+     */
     get isSelected(): Promise<boolean>;
+    /**
+     * Assert the header cell is selected, retrying until the expect timeout.
+     *
+     * @example
+     * test("column is selected", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   // ...select the currency column
+     *   await table.headerCell("currency").assertSelected();
+     * });
+     */
     assertSelected(): Promise<void>;
 }

package/types/index.d.ts

@@ -1,4 +1,6 @@
 export { PlaywrightPageObject } from "./PlaywrightPageObject";
+export { PwChart } from "./PwChart";
+export { type ChartDataPointInfo, PwChartDataPoint } from "./PwChartDataPoint";
 export { PwComponent, type PwComponentTarget } from "./PwComponent";
 export { PwContextMenu } from "./PwContextMenu";
 export { PwMenuItem } from "./PwMenuItem";