@vuu-ui/vuu-playwright-helpers 4.0.0-alpha.22 → 4.0.0-alpha.23

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.0-alpha.22",
+  "version": "4.0.0-alpha.23",
   "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": "4.0.0-alpha.22"
+    "@vuu-ui/vuu-protocol-types": "4.0.0-alpha.23"
   },
   "peerDependencies": {
     "@playwright/test": "^1.62.1"

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

@@ -0,0 +1,88 @@
+import { type Locator, type Page } from "@playwright/test";
+import { PlaywrightPageObject } from "./PlaywrightPageObject";
+/**
+ * Identifies the element a component helper operates on. Either a css selector,
+ * resolved against the page, or a Locator.
+ */
+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;
+    protected abstract readonly defaultCssSelector: string;
+    /**
+     * @param page the Playwright page
+     * @param target optional css selector or Locator for the component, overrides defaultCssSelector
+     */
+    constructor(page: Page, target?: PwComponentTarget | undefined);
+    /**
+     * 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;
+    /**
+     * Wait until the component is attached and visible. Resolves with the
+     * component, so it can be chained.
+     *
+     * @example
+     * const menu = await new PwContextMenu(page).isReady();
+     */
+    isReady(options?: {
+        timeout?: number;
+    }): Promise<this>;
+    /**
+     * 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

@@ -0,0 +1,173 @@
+import { type Locator, type Page } from "@playwright/test";
+import { PwComponent } from "./PwComponent";
+import { PwMenuItem } from "./PwMenuItem";
+/**
+ * A context menu (or one of its sub menus). Usually obtained from
+ * PwTable.showContextMenu.
+ *
+ * @example
+ * test("cell menu", async ({ page }) => {
+ *   const table = new PwTable(page);
+ *   const menu = await table.showContextMenu("ric", 2);
+ *   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();
+ * });
+ */
+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. 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 (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>;
+    /**
+     * Press key(s) within the menu. Keys are sent to the focused element, which
+     * is assumed to be within the menu. Multiple keys are pressed without waiting
+     * for the menu to respond, use assertFocusedMenuItem between key presses where
+     * a key depends on the focus change of the previous key.
+     *
+     * @example
+     * 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. 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

@@ -0,0 +1,196 @@
+import { type Locator } from "@playwright/test";
+import { PwComponent } from "./PwComponent";
+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 (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 (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/selector-utils.d.ts

@@ -0,0 +1,3 @@
+export declare const cssAttributeValue: (value: string) => string;
+export declare const byDataIcon: (iconName: string) => string;
+export declare const byId: (id: string) => string;