@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.0

package/skills/testing/SKILL.md

@@ -4,18 +4,21 @@ description: >
   Write tests against TMDataGrid from a consuming app - Playwright or React
   Testing Library. Covers the data-dg-part contract, data-row-id/data-column-id
   coordinates, naming a grid with data-testid, the roles and ARIA the grid
-  publishes, the cell/gridcell role flip under cell selection, reaching rows
-  past virtualization with data-dg-row-count and scrollToRow, and waiting on
-  aria-busy. Load when writing or fixing tests that drive a grid, or when a
-  selector for a row, cell or control does not resolve.
+  publishes, the cell/gridcell role flip under cell selection, the surfaces that
+  render in a portal (the menu, the export picker, Select listboxes), reaching
+  rows past virtualization with data-dg-row-count, scrollToRow and
+  data-dg-scroll-container, waiting on aria-busy, and the DataGrid page object.
+  Load when writing or fixing tests that drive a grid, or when a selector for a
+  row, cell or control does not resolve.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/testing.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGrid.tsx'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGridTable.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/testing.md'
+  - 'Jielga/TMDataGrid:playwright/support/DataGrid.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGridTable.tsx'
 ---
 
 # TMDataGrid - Testing
@@ -33,6 +36,11 @@ The grid mints no `data-testid` of its own - that attribute belongs to the app,
 and Playwright's `testIdAttribute` is configurable. `@mantine/core` and
 `@tanstack/*` ship none either.
 
+Adding, changing and deleting rows, the draft store, and where a new row's
+temporary id goes at commit are in the `testing-editing` skill. Running the grid
+in a real browser through Playwright's `mount` fixture - virtualization, resize,
+drag, pinning, clipboard - is in the `testing-components` skill.
+
 ## Naming a grid
 
 Parts repeat across grids on a page. Name the grid, scope through it:
@@ -52,70 +60,134 @@ accessible name belongs to the element carrying the `grid` role.
 | Element | Role | Key attributes |
 | --- | --- | --- |
 | Grid | `table`, or `grid` under cell selection | `aria-rowcount`, `aria-colcount`, `aria-busy`, `data-dg-row-count` |
+| Scroll container | - | `data-dg-scroll-container` - the element to scroll |
 | Body row | `row` | `data-row-id`, `aria-rowindex`, `data-selected`, `data-highlighted`, `data-grouped`, `data-pinned`, `data-deleted` |
 | Body cell | `cell`, or `gridcell` under cell selection | `data-row-id`, `data-column-id`, `data-editing`, `data-dirty`, `data-invalid`, `data-focused` |
 | Header cell | `columnheader` | `data-column-id`, `aria-sort` |
 
 Body cells carry no `data-dg-part` - the coordinate pair already names them.
+The `editor` part of an open cell carries the same pair, so a cell locator is
+`[data-row-id="42"][data-column-id="total"]:not([data-dg-part])`; without the
+exclusion it matches two elements while the cell is being edited.
+
+State attributes are present only while they apply: `data-selected`,
+`data-new`, `data-invalid` and the rest are rendered as `"true"` while the
+state holds and omitted otherwise, so `[data-new]` and `[data-new="true"]`
+match the same rows, and the negative is `:not([data-new])` in CSS and
+`not.toHaveAttribute("data-new")` in a test.
 
 ## Parts
 
 **Whole-grid** (unique, no coordinate needed): `toolbar`, `summary-count`,
 `loading`, `search`, `search-clear`, `filter-button`, `filter-panel`,
-`filter-panel-close`, `filter-add`, `filter-clear-all`, `filter-pills`,
-`columns-button`, `columns-panel`, `columns-search`, `columns-toggle-all`,
-`columns-reset`, `footer`, `page-size`, `page-range`, `page-prev`, `page-next`,
-`summary-row`, `pinned-top`, `pinned-bottom`, `select-all`,
-`details-toggle-all`, `save-all`, `discard-all`, `editor-confirm`,
-`editor-cancel`, `editor-input`, `sort-index`.
+`filter-popup`, `filter-sidebar`, `filter-panel-close`, `filter-add`,
+`filter-clear-all`, `filter-pills`, `header-filter-row`,
+`menu-button`, `menu-export`, `menu-export-selected`, `export-picker`,
+`export-picker-search`, `export-picker-hint`, `export-picker-count`,
+`export-column-all`, `export-picker-confirm`, `export-picker-cancel`,
+`columns-panel`, `columns-search`, `columns-toggle-all`,
+`columns-reset`, `footer`, `page-size`, `page-range`, `page-number`,
+`page-prev`, `page-next`, `summary-row`, `pinned-top`, `pinned-bottom`,
+`select-all`, `details-toggle-all`, `save-all`, `discard-all`,
+`editor-confirm`, `editor-cancel`, `editor-input`, `sort-index`, `tab-guard`.
 
 **Keyed by `data-row-id`**: `row`, `entry-row`, `details`, `select-row`,
 `details-toggle`, `group-toggle`, `edit-row`, `delete-row`, `save-row`,
 `cancel-row`, `row-state`, `revert-row`, `restore-row`, `confirm-new-row`,
-`discard-new-row`.
+`discard-new-row`, `open-rows-note`.
 
 **Keyed by `data-column-id`**: `header`, `header-sort`, `header-menu`,
-`header-filter`, `filter-row`, `filter-pill`, `columns-toggle`.
+`header-resize` (the resize handle; present only when the column can resize),
+`header-filter` (absent under `filters.inHeader`), `header-filter-cell`,
+`header-filter-operator`, `filter-row`, `filter-pill`, `columns-toggle`,
+`export-column`.
 
 **Keyed by both**: `editor`.
 
 Inside a `filter-row` the controls are `filter-column`, `filter-operator` and
-`filter-value` - or `filter-value-from` / `filter-value-to` for `between`.
+`filter-value` - or `filter-value-from` / `filter-value-to` for `between` - and
+`filter-remove` is its ✕. None of them carries `data-column-id`; scope through
+the row. Inside a `filter-pill`, `filter-pill-remove` is the ✕.
+`TMDataGridFilterPills` renders where you place it; outside the root, scope
+through its own container rather than through the grid.
 
 A column declaring `meta.filter.control` or `meta.edit.editor` renders your own
 component in that slot, so `filter-value` and `editor-input` cover the built-ins
 only. `filter-row` and `editor` still hold; scope through them.
 
+Sorting: click `header`. `header-sort` is hidden until the header is hovered;
+it shows the state, and `aria-sort` on the header is the assertion.
+
+## Portals
+
+These surfaces render at the end of `<body>`, outside the grid's root, so a
+locator scoped to the root never finds them:
+
+- the `TMDataGrid.Menu` dropdown - `page.getByRole("menu")`, holding
+  `columns-toggle`, `columns-toggle-all`, `columns-reset`, `menu-export`,
+  `menu-export-selected`
+- a column's menu, opened by `header-menu` (hover the header first) or a right
+  click on the header - `page.getByRole("menu")`; its items (sort, filter,
+  group, pin, hide) carry no part, so reach one by role and label,
+  `menu.getByRole("menuitem", { name: "Group by Location" })` - a translated
+  label
+- the `header-filter-operator` menu - `page.getByRole("menu")`
+- the export column picker - `page.getByRole("dialog")`, holding the
+  `export-*` parts
+- the listbox of every `Select` or `MultiSelect` the grid renders -
+  `page-size`, `filter-column`, `filter-operator`, and the `filter-value` of a
+  boolean or select-type filter - the element named by the input's
+  `aria-controls`; each option carries its value in `value`
+
+One menu or dialog is open at a time, so the page-level locator is unambiguous.
+`filter-popup` and `filter-sidebar` render inside the root.
+
 ## A page object
 
+The full class is on the Testing docs page and in the repository at
+`playwright/support/DataGrid.ts`; it is the one the grid's own suite runs
+against the docs demos. The shape:
+
 ```ts
 import { type Locator, type Page, expect } from "@playwright/test";
 
 type PartKey = { rowId?: string; columnId?: string };
 
 export class DataGrid {
+  readonly page: Page;
   readonly root: Locator;
   readonly grid: Locator;
 
-  constructor(page: Page, testId: string) {
-    this.root = page.getByTestId(testId);
-    this.grid = this.root.getByRole("table");
+  /** `root` is the element carrying `data-dg-root`. */
+  constructor(root: Locator) {
+    this.page = root.page();
+    this.root = root;
+    this.grid = root.getByRole("table").or(root.getByRole("grid"));
+  }
+
+  static byTestId(page: Page, testId: string): DataGrid {
+    return new DataGrid(page.getByTestId(testId));
   }
 
   part(name: string, key: PartKey = {}): Locator {
-    return this.root.locator(
-      `[data-dg-part="${name}"]` +
-        (key.rowId === undefined ? "" : `[data-row-id="${key.rowId}"]`) +
-        (key.columnId === undefined ? "" : `[data-column-id="${key.columnId}"]`),
-    );
+    return this.root.locator(partSelector(name, key));
+  }
+
+  /** A part inside the open menu dropdown, which renders in a portal. */
+  menuPart(name: string, key: PartKey = {}): Locator {
+    return this.page.getByRole("menu").locator(partSelector(name, key));
   }
 
   cell({ rowId, columnId }: { rowId: string; columnId: string }): Locator {
     return this.root.locator(
-      `[data-row-id="${rowId}"][data-column-id="${columnId}"]`,
+      `[data-row-id="${rowId}"][data-column-id="${columnId}"]:not([data-dg-part])`,
     );
   }
 
+  async sortBy(columnId: string): Promise<void> {
+    await this.part("header", { columnId }).click();
+  }
+
   async expectRowCount(count: number): Promise<void> {
     await expect(this.grid).toHaveAttribute("data-dg-row-count", String(count));
   }
@@ -126,6 +198,31 @@ export class DataGrid {
 }
 ```
 
+The full class adds `search`, `filterBy` (adds a filter row for the column
+when the panel has none; fills the built-in text and number inputs, so a
+select-type filter takes `chooseOption` on its `filter-value` instead),
+`toggleColumn`, `openColumnMenu` (hovers the header, clicks `header-menu`,
+returns the menu), `chooseOption` (an option of a portaled `Select`, by value),
+and the editing methods of the `testing-editing` skill.
+
+## Recipes
+
+`grid` is a `DataGrid`; the parts are the steps, the attributes are the proof.
+
+| Interaction | Steps | Assertion |
+| --- | --- | --- |
+| Quick search | `grid.search("Cecilia")`; `search-clear` | `grid.expectRowCount(10)`, then the full count |
+| Sort | `grid.sortBy("lastName")` once, then again | `aria-sort` on `header`: `ascending`, then `descending` |
+| Filter | `grid.filterBy({ columnId, value })`; `filter-clear-all` | `grid.expectRowCount(n)`, then the full count |
+| Remove a filter | `filter-remove` in its `filter-row`, or `filter-pill-remove` in its `filter-pill` | the `filter-pill` has count 0; the row count |
+| Hide a column | `grid.toggleColumn("location")`; `grid.menuPart("columns-reset")` | the `header` has count 0, then is visible |
+| Page | `page-next`; `grid.chooseOption({ select: grid.part("page-size"), value: "50" })` | `page-range` text changes, first `row` has a new `data-row-id`; `grid.expectRowCount(50)` |
+| Select rows | `select-row` of a row; `select-all` | `data-selected="true"` on the `row`; `[data-dg-part="row"]:not([data-selected])` has count 0 |
+| Group | `grid.openColumnMenu("location")`, the "Group by" item; `group-toggle` of a group row | rows carry `data-grouped`; `data-dg-row-count` grows on expand, shrinks on collapse |
+| Load more | scroll `data-dg-scroll-container` to `scrollHeight` | `data-dg-row-count` grows; `grid.expectSettled()` |
+| Export | `menu-button`, then `menu-export` in the menu | `page.waitForEvent("download")`, `download.suggestedFilename()` |
+| Edit a cell | `grid.cell(...).dblclick()`, `grid.fillRow(rowId, { columnId: value })`, Enter | the cell's text; Escape instead of Enter leaves it unchanged |
+
 ## Virtualization
 
 Only the rows in the viewport plus overscan are in the DOM. A row at index 500
@@ -138,7 +235,10 @@ otherwise. (`aria-rowcount` also counts the header and summary rows.)
 **Reach a row by narrowing to it** - filter or search. Faster, more stable, and
 what a user would do. Where the row must be reached in place,
 `grid.scrollToRow({ rowId, align })` moves the virtualizer and answers whether
-the row was reachable; from Playwright that needs the app to expose the api.
+the row was reachable; from Playwright that needs the app to expose the api on
+`window`. Scrolling the element carrying `data-dg-scroll-container` moves the
+virtualizer without it, and is also how an infinite-scroll grid is made to
+load its next page.
 
 ## Waiting
 
@@ -165,14 +265,32 @@ layout, so the count depends on the stubbed element size. Assert
 ### getByRole("cell") on a grid with cell selection
 
 `cellSelection` turns every `cell` into a `gridcell`, and the grid's `table`
-into a `grid`, because a widget with a keyboard cursor is not a static table.
-Tests written on the role break when the feature is switched on. Query cells by
+into a `grid`. Tests written on the role break when the feature is switched on. Query cells by
 `[data-row-id][data-column-id]` instead.
 
+### Matching a cell while it is edited
+
+`[data-row-id="42"][data-column-id="total"]` matches the cell and the `editor`
+inside it once the cell is open, and strict mode fails on the pair. Add
+`:not([data-dg-part])`.
+
+### Clicking header-sort to sort
+
+The arrow is `display: none` until the header is hovered, so the click waits
+for visibility and times out. Click `header`; `aria-sort` on it is the result.
+
+### Reaching the menu through the root
+
+`orders.locator('[data-dg-part="columns-toggle"]')` never resolves: the
+dropdown renders in a portal at the end of `<body>`. Use
+`page.getByRole("menu")` after `menu-button` is clicked. The same goes for the
+export picker (`dialog`) and every `Select` listbox (`aria-controls`).
+
 ### Expecting a row far down the list to exist
 
-`dg-row-450` has no element until it is scrolled to, so the locator times out
-with no useful message. Filter or search down to it first.
+`[data-row-id="450"]` has no element until it is scrolled to, so the locator times out
+with no useful message. Filter or search down to it first, or scroll
+`data-dg-scroll-container`.
 
 ### Unscoped parts with two grids on a page
 
@@ -196,4 +314,4 @@ different column than it did. Use `[data-column-id]`.
 
 `data-dg-part="loading"` only renders where `TMDataGrid.LoadingIndicator` was
 placed, and only while `meta.loading` is true. `aria-busy` on the grid is set
-regardless of whether that component is rendered.
+regardless of whether that component is rendered.

package/skills/testing-components/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: testing-components
+description: >
+  Test a TMDataGrid in a real browser with Playwright component tests: the
+  stories-and-gallery model of Playwright 1.62+, the mount fixture, how a story
+  wraps the grid (MantineProvider env="test", a fixed-size container, the api on
+  window for scrollToRow), and the browser-only behaviour worth testing there -
+  virtualization, column resize through header-resize, column reorder by drag,
+  sticky pinned columns, the clipboard. Load when setting up or writing
+  Playwright component tests for a grid, or when a jsdom test cannot observe
+  layout, scrolling or drag.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '2.0.0'
+sources:
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/testing.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/test/gallery/main.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/test/stories/Grid.story.tsx'
+  - 'Jielga/TMDataGrid:playwright/components/virtualization.spec.ts'
+---
+
+# TMDataGrid - Component tests in a browser
+
+Builds on the `testing` skill: parts are `[data-dg-part]`, coordinates are
+`[data-row-id]` / `[data-column-id]`, and `DataGrid` is the page object.
+
+jsdom has no layout. The virtualizer mounts a handful of rows whatever the data
+says, a drag never moves anything, and jsdom does not apply `position: sticky`.
+The behaviour below needs a browser:
+
+- virtualization - rows mount and unmount as the body scrolls; `scrollToRow`
+- column resize - a drag on `header-resize`, and double-click to fit
+- column reorder - a header dragged onto another header (native HTML5 drag)
+- pinned columns - sticky offsets while the body scrolls horizontally
+- sticky header and summary row while the body scrolls vertically
+- the clipboard - Ctrl+C on a cell selection
+
+## The model
+
+Playwright 1.62 replaced `@playwright/experimental-ct-react` with three pieces
+that live in plain `@playwright/test`:
+
+- **a story** - a `*.story.tsx` file; each named export is one scenario, a
+  component with hard-coded data, options and providers
+- **a gallery** - one page served by your own dev server that discovers the
+  story files, exposes `window.mount({ story, props })` and `window.unmount()`,
+  and renders into `#root` through one reused React root
+- **`mount`** - a built-in fixture: `await mount("Orders/Virtualized")`
+  navigates to the gallery (`baseURL`), mounts the story and returns a
+  `Locator` for the gallery root
+
+The story id is the file path under the stories folder without `.story.tsx`,
+then `/` and the export name. `mount` accepts any string, so a renamed story
+fails at run time, not under `tsc`; registering the ids in Playwright's
+`Stories` interface gives completion and prop checking:
+
+```ts
+declare module "@playwright/test" {
+  interface Stories {
+    "Orders/Virtualized": typeof Virtualized;
+  }
+}
+```
+
+What the gallery page must expose is in Playwright's docs
+(https://playwright.dev/docs/test-components); the grid's own gallery is a few
+dozen lines over `import.meta.glob`.
+
+Project config, next to the page project:
+
+```ts
+{
+  name: "components",
+  testDir: "playwright/components",
+  use: {
+    baseURL: "http://localhost:5274/",
+    serviceWorkers: "block",
+    permissions: ["clipboard-read", "clipboard-write"],
+  },
+}
+```
+
+with a `webServer` entry such as
+`{ command: "npm run gallery", url: "http://localhost:5274/" }`. Every
+`webServer` entry starts on every run; Playwright does not scope them to a
+project.
+
+## Writing a story for the grid
+
+The story owns everything the grid needs:
+
+```tsx
+// Orders.story.tsx
+declare global {
+  interface Window {
+    __grid?: TMDataGridApi<Order>; // for scrollToRow from the test
+  }
+}
+
+export const Virtualized = () => {
+  const grid = useTMDataGrid<Order>({
+    data: orders, // 5000 rows
+    columns,
+    getRowId: (row) => row.id,
+  });
+  useEffect(() => {
+    window.__grid = grid;
+  }, [grid]);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", height: 400 }}>
+      <TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }} data-testid="orders">
+        <TMDataGrid.Table<Order> />
+      </TMDataGrid>
+    </div>
+  );
+};
+```
+
+- **`<MantineProvider env="test">`** around every story, in the gallery or in
+  the story. It turns Mantine's transitions off, so a panel is open the moment
+  the click lands.
+- **A flex column of fixed height,** with `flex: 1` and `minHeight: 0` on the
+  grid. The grid root is a shrinkable flex item; in a plain block it grows to
+  fit every row, nothing scrolls, and the virtualization test proves nothing.
+  Give the pinned story a width smaller than its columns (`minSize` sets a
+  fluid column's floor; `size` alone does not widen it), so the body overflows
+  horizontally.
+- **The api on `window`** only where a test calls `scrollToRow`. Everything
+  else is reachable through the DOM contract. Declare the global in the story
+  and again in the spec, which is typechecked apart from it.
+- **No props unless needed.** One export per scenario, and `mount(id)` needs
+  no generic.
+
+## Writing the test
+
+`mount` returns the gallery root; the page object takes the grid root inside it:
+
+```ts
+declare global {
+  interface Window {
+    __grid?: { scrollToRow(target: { rowId: string; align?: "start" | "center" | "end" }): boolean };
+  }
+}
+
+test("reaches a row past the viewport", async ({ mount, page }) => {
+  const component = await mount("Orders/Virtualized");
+  const grid = new DataGrid(component.locator("[data-dg-root]"));
+  await grid.expectRowCount(5000);
+  await expect(grid.part("row", { rowId: "4500" })).toHaveCount(0);
+
+  const found = await page.evaluate(() => {
+    return window.__grid!.scrollToRow({ rowId: "4500", align: "center" });
+  });
+  expect(found).toBe(true);
+  await expect(grid.part("row", { rowId: "4500" })).toBeVisible();
+});
+```
+
+### Recipes
+
+**Virtualization.** `data-dg-row-count` is the data; the number of
+`[data-dg-part="row"]` elements is the window. Asserting that the second is
+far below the first is the one place counting row elements is right. Scroll
+the element carrying `data-dg-scroll-container` to its `scrollHeight` and the
+last row appears.
+
+**Resize.** `header-resize` is the handle, keyed by `data-column-id`:
+
+```ts
+const handle = grid.part("header-resize", { columnId: "name" });
+const box = (await handle.boundingBox())!;
+await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+await page.mouse.down();
+await page.mouse.move(box.x + 80, box.y, { steps: 8 });
+await page.mouse.up();
+```
+
+Then compare the header's `boundingBox().width` before and after. A
+`dblclick()` on the handle fits the column to its content.
+
+**Reorder.** `await grid.part("header", { columnId: "city" }).dragTo(grid.part("header", { columnId: "name" }), { targetPosition: { x: 10, y: 10 } })`
+drops `city` before `name`; read the new order from `[data-dg-part="header"]`
+`data-column-id`s. A header dragged across a pinned lane does not move.
+
+**Pinning.** Scroll the scroll container horizontally (`scrollLeft`) and compare
+`boundingBox().x` of a pinned header before and after: unchanged, while an
+unpinned header moved. A pinned header and a body cell of the same column share
+the same `x`.
+
+**Sticky header and summary row.** Scroll vertically; `boundingBox().y` of the
+header row (`[data-dg-header-row]`) and of `summary-row` do not change, and
+both stay inside the scroll container's box.
+
+**Clipboard.** In a story with `cellSelection` on: click a cell, shift-click
+another, `page.keyboard.press("Control+C")`, then
+`page.evaluate(() => navigator.clipboard.readText())`. Cells are separated by
+a tab and rows by `\r\n`. Needs the `permissions` above; Chromium only.
+
+## Common mistakes
+
+### Mounting without a provider
+
+A story rendered outside `MantineProvider` throws on the first Mantine
+component. Put the provider in the gallery's `window.mount`, so no story can
+forget it.
+
+### A story with no height
+
+The grid fills its container. With `height: auto` the container grows with the
+rows, nothing scrolls, and the virtualizer mounts everything; the test passes
+for the wrong reason or hangs on 5000 rows.
+
+### Building JSX in the test
+
+The test runs in Node and the component in the browser; there is no JSX across
+that boundary. A scenario is a story export. A test that needs a different
+composition gets another export.
+
+### Passing a callback as a prop
+
+Callbacks do not cross to the browser either. The story owns the state and the
+callbacks, and writes what a test must see into the DOM - a hidden input, or
+the grid's own `data-*` attributes, which already carry most of it.
+
+### Counting row elements everywhere
+
+Outside the virtualization claim itself, assert `data-dg-row-count`. The
+window size depends on the viewport, overscan and row height, and changes with
+`devices` presets.