@vuu-ui/vuu-playwright-helpers 3.5.22 → 3.5.23

package/package.json

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

package/src/PwTable.js

@@ -3,6 +3,7 @@ import { PwComponent } from "./PwComponent.js";
 import { PwContextMenu } from "./PwContextMenu.js";
 import { PwTableHeaderCell } from "./PwTableHeaderCell.js";
 import { byDataIcon, cssAttributeValue } from "./selector-utils.js";
+const SCROLL_TOLERANCE = 1;
 const byAriaRowIndex = (ariaRowIndex)=>`[aria-rowindex="${ariaRowIndex}"]:scope`;
 const xpathStringLiteral = (value)=>{
     if (!value.includes("'")) return `'${value}'`;
@@ -17,6 +18,56 @@ class PwTable extends PwComponent {
     get scrollbarContainer() {
         return this.locator.locator(".vuuTable-scrollbarContainer");
     }
+    scrollPosition() {
+        return this.scrollbarContainer.evaluate(({ scrollLeft, scrollTop })=>({
+                scrollLeft,
+                scrollTop
+            }));
+    }
+    scrollUp(distance) {
+        return this.scroll("vertical", -1, distance);
+    }
+    scrollDown(distance) {
+        return this.scroll("vertical", 1, distance);
+    }
+    scrollLeft(distance) {
+        return this.scroll("horizontal", -1, distance);
+    }
+    scrollRight(distance) {
+        return this.scroll("horizontal", 1, distance);
+    }
+    async scroll(axis, direction, distance) {
+        if ("number" == typeof distance && distance < 0) throw Error("PwTable, scroll, distance must not be negative, use the opposite direction");
+        await this.scrollbarContainer.evaluate((el, { axis, direction, distance })=>{
+            const vertical = "vertical" === axis;
+            const current = vertical ? el.scrollTop : el.scrollLeft;
+            const max = vertical ? el.scrollHeight - el.clientHeight : el.scrollWidth - el.clientWidth;
+            const pos = "start" === distance ? 0 : "end" === distance ? max : current + direction * ("page" === distance ? el.clientHeight : distance);
+            el.scrollTo({
+                [vertical ? "top" : "left"]: Math.min(max, Math.max(0, pos)),
+                behavior: "instant"
+            });
+        }, {
+            axis,
+            direction,
+            distance
+        });
+        await expect.poll(()=>this.isContentScrollSynced(), {
+            message: "PwTable, content container scroll position not synced"
+        }).toBe(true);
+    }
+    isContentScrollSynced() {
+        return this.locator.evaluate((table, tolerance)=>{
+            const scrollbar = table.querySelector(".vuuTable-scrollbarContainer");
+            const content = table.querySelector(".vuuTable-contentContainer");
+            if (!scrollbar || !content) return false;
+            const isSynced = (sourcePos, sourceMax, targetPos, targetMax)=>{
+                const expected = sourceMax > 0 ? sourcePos / sourceMax * targetMax : 0;
+                return Math.abs(targetPos - expected) <= tolerance;
+            };
+            return isSynced(scrollbar.scrollTop, scrollbar.scrollHeight - scrollbar.clientHeight, content.scrollTop, content.scrollHeight - content.clientHeight) && isSynced(scrollbar.scrollLeft, scrollbar.scrollWidth - scrollbar.clientWidth, content.scrollLeft, content.scrollWidth - content.clientWidth);
+        }, SCROLL_TOLERANCE);
+    }
     row(row) {
         return this.locator.locator(`[aria-rowindex="${row}"]`);
     }

package/types/PwTable.d.ts

@@ -4,6 +4,20 @@ import { PwComponent } from "./PwComponent";
 import { PwContextMenu } from "./PwContextMenu";
 import { PwTableHeaderCell } from "./PwTableHeaderCell";
 type AriaRole = "cell" | "textbox" | "combobox";
+/**
+ * How far to scroll: 'start' or 'end' scroll to that end of the axis, a number
+ * scrolls by that many pixels in the direction of the method.
+ */
+export type ScrollDistance = "start" | "end" | number;
+/**
+ * As ScrollDistance, plus 'page' to scroll vertically by the height of the
+ * viewport (as the PageUp and PageDown keys do).
+ */
+export type VerticalScrollDistance = ScrollDistance | "page";
+export interface ScrollPosition {
+    scrollLeft: number;
+    scrollTop: number;
+}
 /**
  * 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).
@@ -39,6 +53,80 @@ export declare class PwTable extends PwComponent {
      * });
      */
     get scrollbarContainer(): Locator;
+    /**
+     * The scroll position of the scrollbar container.
+     *
+     * @example
+     * test("scrolled to top", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   expect((await table.scrollPosition()).scrollTop).toBe(0);
+     * });
+     */
+    scrollPosition(): Promise<ScrollPosition>;
+    /**
+     * Scroll up, by a number of pixels, a page (the height of the viewport), or
+     * to the 'start' (top) or 'end' (bottom). Scrolls the scrollbar container,
+     * as a user dragging the scrollbar would, and resolves once the content
+     * container has been scrolled to match.
+     *
+     * @example
+     * test("scroll back to top", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollDown("page");
+     *   await table.scrollUp("start");
+     *   await expect(table.row(2)).toBeInViewport();
+     * });
+     */
+    scrollUp(distance: VerticalScrollDistance): Promise<void>;
+    /**
+     * Scroll down, by a number of pixels, a page (the height of the viewport),
+     * or to the 'start' (top) or 'end' (bottom). Scrolls the scrollbar
+     * container, as a user dragging the scrollbar would, and resolves once the
+     * content container has been scrolled to match.
+     *
+     * @example
+     * test("scroll to last row", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollDown("end");
+     *   await expect(table.row(1001)).toBeInViewport();
+     * });
+     */
+    scrollDown(distance: VerticalScrollDistance): Promise<void>;
+    /**
+     * Scroll left, by a number of pixels, or to the 'start' (leftmost) or 'end'
+     * (rightmost). Scrolls the scrollbar container, as a user dragging the
+     * scrollbar would, and resolves once the content container has been
+     * scrolled to match.
+     *
+     * @example
+     * test("scroll back to first column", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollRight("end");
+     *   await table.scrollLeft("start");
+     *   await expect(table.locateCell(2, 1)).toBeInViewport();
+     * });
+     */
+    scrollLeft(distance: ScrollDistance): Promise<void>;
+    /**
+     * Scroll right, by a number of pixels, or to the 'start' (leftmost) or
+     * 'end' (rightmost). Scrolls the scrollbar container, as a user dragging the
+     * scrollbar would, and resolves once the content container has been
+     * scrolled to match.
+     *
+     * @example
+     * test("scroll right by 200px", async ({ page }) => {
+     *   const table = new PwTable(page);
+     *   await table.scrollRight(200);
+     *   expect((await table.scrollPosition()).scrollLeft).toBe(200);
+     * });
+     */
+    scrollRight(distance: ScrollDistance): Promise<void>;
+    private scroll;
+    /**
+     * The table keeps the content container at the same proportional scroll
+     * position as the scrollbar container.
+     */
+    private isContentScrollSynced;
     /**
      * Row Locator by 1-based aria row index, including headers.
      *

package/types/index.d.ts

@@ -5,6 +5,6 @@ export { PwColumnPicker } from "./PwColumnPicker";
 export { PwComponent, type PwComponentTarget } from "./PwComponent";
 export { PwContextMenu } from "./PwContextMenu";
 export { PwMenuItem } from "./PwMenuItem";
-export { PwTable } from "./PwTable";
+export { PwTable, type ScrollDistance, type ScrollPosition, type VerticalScrollDistance, } from "./PwTable";
 export { PwTableFooter } from "./PwTableFooter";
 export { PwTableHeaderCell } from "./PwTableHeaderCell";