@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.1

package/skills/server-side/SKILL.md

@@ -4,16 +4,22 @@ description: >
   Drive TMDataGrid from a server with TanStack manual modes - manualPagination,
   manualSorting, manualFiltering, rowCount, controlled state and onXChange
   callbacks. Covers the loading and totalRowCount meta fields, forwarding the
-  plain-JSON columnFilters model to an API with isFilterActive, persistence
-  interaction, and row selection across pages. Load when the grid is backed by a
-  paginated API rather than a local array.
+  plain-JSON columnFilters model to an API with activeColumnFilters, mapping
+  filters, sorting and the page index onto an endpoint's own query language
+  (field table, operator table, the three value shapes, meta.filter.operators
+  for an endpoint that answers only some operators, keying the fetch on the
+  request, paging against a page envelope), the first-page reset on a query
+  change, persistence interaction, and row selection across pages. Load when the
+  grid is backed by a paginated API rather than a local array, or when
+  translating grid filters into server-side queries.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.1'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/server-side.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-side.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-query.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'
 ---
 
 # TMDataGrid - Server-side data
@@ -68,12 +74,32 @@ const grid = useTMDataGrid({
 | --- | --- | --- |
 | Rendered rows | The current page, sliced locally | The rows returned by the server |
 | Footer total | Pre-paginated row count | `options.rowCount` |
-| `SummaryCount` total | Pre-filtered row count | `meta.totalRowCount` |
+| `SummaryCount` total | Pre-filtered row count | `meta.totalRowCount`; the count alone without it |
 | Loading state | Not applicable | `meta.loading` |
 
 Column menus, the filter panel and the column manager behave identically in both
 modes.
 
+## The page index
+
+Under `manualPagination` the grid resets `pageIndex` to 0 whenever the query
+changes - a column filter, the quick search or the sort - so the next request
+never asks for page 8 of a result set that now has three. The reset lands in
+the same event as the change, so one request goes out. Pass the plain setters
+as the change callbacks; do not pair them with a page reset of your own.
+
+`resetPageOnQueryChange: false` switches it off. TanStack's
+`autoResetPageIndex` is a different rule: it defaults to `!manualPagination`
+and fires on a change to `data`, which server-side is the response landing.
+
+## Column options
+
+`meta.options: "faceted"` reads the distinct values in `data`, which
+server-side is one page of them - the dropdown then offers whatever was on the
+page the user is looking at. Declare the set as a list or a function instead.
+The grid warns once per column when a faceted column resolves under
+`manualFiltering` or `manualPagination`.
+
 ## Sending filters
 
 Filter values are plain JSON, so `columnFilters` forwards without transformation:
@@ -85,17 +111,136 @@ Filter values are plain JSON, so `columnFilters` forwards without transformation
 ]
 ```
 
-Translate at the API boundary, and skip entries whose value is still empty -
-those match all rows:
+Translate at the API boundary. `activeColumnFilters` hands back the entries
+that narrow anything, typed - `ColumnFiltersState` types `value` as `unknown`,
+and an entry whose value is still empty matches all rows:
 
 ```ts
-import { isFilterActive } from "@jielga/tmdatagrid";
+import { activeColumnFilters } from "@jielga/tmdatagrid";
 
-const active = columnFilters.filter((filter) => isFilterActive(filter.value));
+const active = activeColumnFilters(columnFilters);
+// [{ id: "lastName", value: { operator: "contains", value: "holm" } }]
 ```
 
+It takes the `columnFilters` array, or the table where the grid owns the slice.
+`isFilterActive(value)` is the single-value test it is built on. Only the
+grid's own `{ operator, value }` shape is read: an entry holding some other
+value - a custom filter control writing raw values - is dropped.
+
 Debounce requests. The filter value input updates on every keystroke.
 
+## Mapping onto the endpoint's query language
+
+An API takes a request body of its own: its own field names, its own operator
+set, its own status codes, and pages counted from 1. The layer between the
+grid's state and that body is one function over two lookup tables, plus one
+function on the way back:
+
+- **A field table** keyed by column id, giving the API field and the cast from
+  the string every filter control writes to the type the field holds
+  (`Number`, an enum code). A column missing from the table is one the API
+  cannot query: the mapping drops the filter rather than sending a field the
+  endpoint would reject.
+- **An operator table** from `TMDataGridFilterOperator` to the API's operators.
+  Several grid operators collapse onto one - a date `before` and a number
+  `lessThan` are both `lt` once the value is cast. Declare it as a `Record`, not
+  a `Partial`, so an operator added by a later grid version fails the build
+  here rather than reaching the server unmapped.
+- **`toRow`** from the API's record to the grid's row type.
+
+```ts
+const QUERY_FIELDS: Record<string, { field: string; cast: (raw: string) => string | number }> = {
+  id: { field: "orderRef", cast: Number },
+  amount: { field: "totalAmount", cast: Number },
+  status: { field: "status", cast: (raw) => STATUS_CODES[raw] ?? raw },
+};
+
+const PREDICATE_OPS: Record<TMDataGridFilterOperator, PredicateOp> = {
+  contains: "like",
+  between: "range",
+  before: "lt",
+  lessThan: "lt",
+  isAnyOf: "in",
+  isEmpty: "isNull",
+  // ...one line for every remaining operator.
+};
+```
+
+### The three value shapes
+
+`TMDataGridFilterValue` is `{ operator, value }`, and the operator decides what
+`value` holds. Branch on all four cases, in this order:
+
+| Operator | `value` | Sent as |
+| --- | --- | --- |
+| `isEmpty`, `isNotEmpty` | Not used | `{ field, op }` |
+| `isAnyOf`, `isNoneOf` | `ReadonlyArray<string>` | `{ field, op, values }` |
+| `between` | `[min, max]`, either end possibly `""` | `{ field, op, from?, to? }` |
+| Everything else | `string` | `{ field, op, value }` |
+
+An empty end of a `between` pair leaves that side open: an absent bound, not an
+empty string. Run `activeColumnFilters` over the slice first so a half-typed
+filter is not sent as a predicate that narrows the result to nothing.
+
+### An endpoint that answers only some operators
+
+Most endpoints do not have every operator the grid has - `like` and `eq` but no
+prefix match is common. Do not offer what you would have to drop.
+`meta.filter.operators` narrows the column to the operators the query can
+express, and the mapping table is declared over exactly that list, so one
+cannot be offered without a mapping or mapped without being offered:
+
+```ts
+const TEXT_OPERATORS = [
+  "contains",
+  "equals",
+  "isEmpty",
+  "isNotEmpty",
+] as const satisfies readonly TMDataGridFilterOperator[];
+
+const TEXT_OPS: Record<(typeof TEXT_OPERATORS)[number], PredicateOp> = {
+  contains: "like",
+  equals: "eq",
+  isEmpty: "isNull",
+  isNotEmpty: "isNotNull",
+};
+
+columnHelper.accessor("customer", {
+  header: "Customer",
+  meta: { filter: { operators: TEXT_OPERATORS } },
+});
+```
+
+A fresh filter opens on `meta.filter.defaultOperator` when set, else on the
+type's default when the list holds it, else on the first entry. The lookup at
+the boundary still returns `undefined` for an unmapped operator: a filter
+restored by `persist` from before the list was narrowed can carry one.
+
+### Keying the fetch on the request
+
+Serialize the request with `JSON.stringify` inside `useMemo` over
+`columnFilters`, `sorting` and `pagination`, and key the fetch effect (or the
+TanStack Query `queryKey`) on that string. Opening the panel and adding an
+empty row moves `columnFilters` but leaves the request unchanged, so nothing is
+sent. The effect owes the server a debounce (the value input updates on every
+keystroke) and a cancel (a `cancelled` flag in the cleanup, or an
+`AbortController` on a real `fetch`).
+
+### Paging against a page envelope
+
+| The API's | The grid's | Written as |
+| --- | --- | --- |
+| `page.number`, counted from 1 | `pagination.pageIndex`, counted from 0 | `number: pageIndex + 1` |
+| `page.totalItems`, the matched count | `rowCount` | `rowCount: page?.totalItems ?? 0` |
+| `page.totalPages` | `state.pageCount`, derived from `rowCount / pageSize` | Nothing; the grid computes it |
+
+Forward `totalPages` only when the server pages by something other than the
+size the grid asked for. `pageCount: -1` when the total is unknown. Show the
+page number through the Footer's `renderPagination` slot with
+`<Controls.PageSize /><Controls.PageNumber /><Controls.Pager />`.
+`meta.totalRowCount` is the unfiltered total, which no filtered response
+carries: take it from a separate count call.
+
 ## Persistence
 
 `persist` works unchanged. `dataKey` restores filters, sorting and pagination
@@ -126,18 +271,26 @@ Without `rowCount` the table derives the total from the rows it was handed -
 one page - so `getPageCount()` returns 1. The footer shows "1–25 of 25" and the
 next-page button is disabled, with no error. Pass the server total.
 
-### Filters sent without isFilterActive
+### Filters sent without activeColumnFilters
 
 An empty filter value stays in `columnFilters` while the user is still typing.
 Forwarded verbatim it becomes `operator: "contains", value: ""` at the API,
-which most backends translate into a real predicate. Filter with
-`isFilterActive` first.
+which most backends translate into a real predicate. Map over
+`activeColumnFilters(columnFilters)` instead of over the slice.
 
 ### SummaryCount without meta.totalRowCount
 
-`SummaryCount` falls back to the pre-filtered row count, which under manual
-filtering is just the current page. It reads "25 of 25" regardless of how many
-rows the server holds. Pass the unfiltered total as `meta.totalRowCount`.
+Without it there is no denominator to show: the pre-filtered row count is the
+current page, so the grid renders the matched count alone rather than a
+plausible-looking wrong total. Pass the unfiltered total as
+`meta.totalRowCount` to get the "42 / 5000" form back.
+
+### Offering operators the endpoint cannot answer
+
+The panel offers every operator of the column's type, and a mapping that drops
+`startsWith` leaves the user with a filter that silently does nothing. Declare
+`meta.filter.operators` on the column with the operators the endpoint answers,
+and type the operator table over that same list.
 
 ### Unstable getRowId across pages
 

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.1'
 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.