@jielga/tmdatagrid 2.0.0-beta.8 → 2.0.0

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.

package/skills/testing-editing/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: testing-editing
+description: >
+  Test TMDataGrid editing flows from Playwright: adding a row through the entry
+  row, where its temporary id (__new__1) goes at commit and at save, finding an
+  added row when the grid does not know the id the app gave it, asserting a
+  failed validation on an entry row, cell and row edits, deletions, and the
+  draft store (data-new, data-draft, data-dirty, data-deleted, row-state,
+  save-all and data-draft-count). Load when writing or fixing a test that adds,
+  edits, deletes or saves rows, or when a locator for a new row stops resolving
+  after the row is committed.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '2.0.0'
+sources:
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/testing.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/editing.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/draft-store.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGridEntryRows.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGridEditColumn.tsx'
+---
+
+# TMDataGrid - Testing editing
+
+Builds on the `testing` skill: parts are `[data-dg-part]`, coordinates are
+`[data-row-id]` / `[data-column-id]`, and `DataGrid` is its page object, built
+with `DataGrid.byTestId(page, "orders")` or `new DataGrid(rootLocator)`.
+
+## The life of an added row
+
+`edit.addRow()` opens an entry row keyed by a temporary id. What happens at ✓
+depends on `editing.draft`, and that decides what a test can hold on to:
+
+| Step | Without `draft` | With `draft: true` |
+| --- | --- | --- |
+| `addRow()` | `[data-dg-part="entry-row"][data-row-id="__new__1"]`; editors are `[data-dg-part="editor"][data-row-id="__new__1"][data-column-id="..."]` | Same |
+| ✓ fails validation | Entry row stays; failing cells carry `data-invalid="true"` | Same |
+| ✓ (`confirm-new-row`) | **Entry row removed, temp id gone.** `onRowAdd({ tempId, value })` runs in the app; the row exists again only when the app puts it in `data`, under the id the app's `getRowId` returns | Becomes a body row **still keyed by the temp id**: `[data-dg-part="row"][data-row-id="__new__1"][data-new="true"][data-draft="true"]`, lane shows `[data-dg-part="row-state"][data-state="new"]`, `[data-dg-part="save-all"]` counts it in `data-draft-count` |
+| Save (`save-all`) | - | As ✓ without `draft`: temp id gone, row comes back through `data` under the app's id |
+| `newRowsSticky: true` | - | The committed row stays an `entry-row` with `data-committed="true"`, outside `data-dg-row-count`, until Save |
+
+The grid never learns the id the app assigns (a database id, a negative
+counter, a uuid - whatever `onRowAdd` or `onSaveDrafts` does). The temp id →
+real id mapping does not exist anywhere in the DOM.
+
+## The rule: find an added row by content, not by id
+
+Once `onRowAdd` or `saveDrafts` has run, the only thing the test knows about
+the row is what it typed. Narrow the grid to a value unique to that row, assert
+that exactly one row is left, read that row's cells:
+
+```ts
+async expectRowAdded(uniqueValue: string, cells: Record<string, string>) {
+  await this.search(uniqueValue);   // or filterBy on a column when there is no quick search
+  await this.expectRowCount(1);     // retries until the app has put the row in data
+  const row = this.part("row");     // exactly one body row now
+  for (const [columnId, text] of Object.entries(cells)) {
+    await expect(
+      row.locator(`[data-column-id="${columnId}"]:not([data-dg-part])`),
+    ).toHaveText(text);
+  }
+  await this.search("");
+}
+```
+
+- The `data-dg-row-count` assertion is the wait. Nothing else signals that
+  `onRowAdd` finished: `aria-busy` reflects `meta.loading` only.
+- Use a value no other row has - put a run id in the name. Two matches means
+  `expectRowCount(1)` fails, correctly.
+- Scoped to the grid and to one column: no `page.getByText`, no virtualization
+  problem, no strict-mode ambiguity.
+
+## Page object methods
+
+Add these to the `DataGrid` class from the `testing` skill:
+
+```ts
+entryRow(): Locator {
+  return this.part("entry-row");
+}
+
+/** Built-in editors of an open row: an entry row, or a row opened in row mode. */
+async fillRow(rowId: string, values: Record<string, string>): Promise<void> {
+  for (const [columnId, value] of Object.entries(values)) {
+    await this.part("editor", { rowId, columnId })
+      .locator('[data-dg-part="editor-input"]')
+      .fill(value);
+  }
+}
+
+async commitEntryRow(rowId: string): Promise<void> {
+  await this.part("confirm-new-row", { rowId }).click();
+}
+
+/** Save in TMDataGrid.DraftActions, waited until the store is empty. */
+async saveDrafts(): Promise<void> {
+  await this.part("save-all").click();
+  await expect(this.part("save-all")).toHaveAttribute("data-draft-count", "0");
+}
+```
+
+`fillRow` covers the built-in editors. A column with `meta.edit.editor` renders
+the app's own component inside the `editor` part; scope through
+`part("editor", { rowId, columnId })` and fill whatever is inside.
+
+## Recipes
+
+### Add a row, without draft
+
+```ts
+await page.getByRole("button", { name: "Add row" }).click(); // the app's button → edit.addRow()
+const tempId = (await grid.entryRow().getAttribute("data-row-id"))!;
+await grid.fillRow(tempId, { name: "Nordkvist-4711", city: "Stockholm" });
+await grid.commitEntryRow(tempId);
+
+await expect(grid.entryRow()).toHaveCount(0);           // entry row gone; tempId is now meaningless
+await grid.expectRowAdded("Nordkvist-4711", { name: "Nordkvist-4711", city: "Stockholm" });
+```
+
+### Add a row, with draft, then save
+
+```ts
+await grid.commitEntryRow(tempId);
+const row = grid.part("row", { rowId: tempId });        // tempId is still the row's id
+await expect(row).toHaveAttribute("data-new", "true");
+await expect(row).toHaveAttribute("data-draft", "true");
+await expect(grid.part("row-state", { rowId: tempId })).toHaveAttribute("data-state", "new");
+await expect(grid.part("save-all")).toHaveAttribute("data-draft-count", "1");
+
+await grid.saveDrafts();
+await expect(row).toHaveCount(0);                       // tempId dies here
+await grid.expectRowAdded("Nordkvist-4711", { city: "Stockholm" });
+```
+
+Reopening a committed draft row: `edit-row` (the lane's pencil) or a
+double-click puts it back in the entry block, still under the temp id; ✕
+(`discard-new-row`) removes it.
+
+### A ✓ that fails validation
+
+```ts
+await grid.commitEntryRow(tempId);
+await expect(grid.entryRow()).toHaveCount(1);           // still open
+await expect(
+  grid.entryRow().locator('[data-column-id="email"]:not([data-dg-part])'),
+).toHaveAttribute("data-invalid", "true");
+```
+
+The cell and the open `editor` inside it share the column id, so the selector
+leaves the editor out.
+
+### Change a cell or a row
+
+```ts
+const cell = grid.cell({ rowId: "42", columnId: "salary" });
+await cell.dblclick();                                  // cell mode: opens the editor
+await grid.fillRow("42", { salary: "52000" });
+await page.keyboard.press("Enter");                     // commits
+
+// Without draft: onCommit ran, the app applied it, the grid holds nothing
+await expect(cell).toHaveText("52 000");
+
+// Under draft: the grid holds it until Save
+await expect(cell).toHaveAttribute("data-dirty", "true");
+await expect(grid.part("row", { rowId: "42" })).toHaveAttribute("data-dirty", "true");
+await expect(grid.part("row-state", { rowId: "42" })).toHaveAttribute("data-state", "edited");
+```
+
+Row mode: `edit-row` opens the row, `fillRow` reaches its editors, `save-row`
+commits, `cancel-row` discards. `cellConfirm` mode: `editor-confirm` /
+`editor-cancel` beside the input, or Enter / Escape.
+
+### Delete a row
+
+```ts
+const before = Number(await grid.grid.getAttribute("data-dg-row-count"));
+await grid.part("delete-row", { rowId: "42" }).click();
+
+// Without draft: onRowDelete ran, the app removed it from data
+await grid.expectRowCount(before - 1);
+
+// Under draft: marked until Save; restore-row undoes the mark
+await expect(grid.part("row", { rowId: "42" })).toHaveAttribute("data-deleted", "true");
+await grid.part("restore-row", { rowId: "42" }).click();
+```
+
+## Attribute values
+
+A state attribute is present, with the value `"true"`, only while it applies:
+`data-new`, `data-draft`, `data-dirty`, `data-deleted` on a body row,
+`data-committed` on an entry row, `data-dirty`, `data-invalid`, `data-editing`
+on a cell. `[data-new]` and `[data-new="true"]` match the same rows,
+`toHaveAttribute("data-new")` and `toHaveAttribute("data-new", "true")` both
+hold, and the negative is `not.toHaveAttribute("data-new")`.
+
+## Common mistakes
+
+### Looking for the new row's text on the page
+
+`page.getByText("Nordkvist")` searches the whole document: other grids, the
+toolbar, a toast. And the row may be virtualized out of the DOM, so the
+locator fails or flakes depending on sort order and viewport. Narrow with
+search or a filter, assert `data-dg-row-count` is 1, read that one row.
+
+### Keeping the temp id after ✓ without draft
+
+`grid.part("row", { rowId: "__new__1" })` never resolves: without `draft` the
+grid drops the entry and the id at ✓, and the row's real id is the app's. Only
+under `draft: true` does the temp id outlive ✓ - and only until Save.
+
+### Waiting for the added row with a timeout
+
+The app's `onRowAdd` may be async. `expectRowCount(1)` after narrowing retries
+until the row is in `data`; a `waitForTimeout` either wastes time or is too
+short on CI.
+
+### Matching the editor with a cell selector
+
+While a cell is open, `[data-row-id="42"][data-column-id="salary"]` matches
+the cell and the `editor` part inside it, and strict mode fails on the pair.
+`DataGrid.cell()` appends `:not([data-dg-part])`; a hand-written locator on a
+row's cells needs the same.
+
+### Asserting the negative with `"false"`
+
+`toHaveAttribute("data-new", "false")` never passes: a state that does not
+apply is an absent attribute, not `"false"`. Use
+`not.toHaveAttribute("data-new")`, and `:not([data-new])` in CSS.
+
+### Asserting a deletion with `toHaveCount(0)`
+
+A row outside the viewport has no element either. Assert `data-dg-row-count`
+dropped by one, or, under `draft`, `data-deleted="true"` on the row.
+
+### Expecting the grid to show the change without draft
+
+Without `draft: true` the grid holds nothing after a commit: no `data-dirty`,
+no `row-state`, `save-all` stays disabled at `data-draft-count="0"`. The
+assertion is the cell's text after the app has applied the change to `data`.

package/src/{tmdatagrid/TMDataGridContext.ts → TMDataGridContext.ts}

@@ -32,27 +32,15 @@ export function useTMDataGridContext(): TMDataGridContextValue {
 }
 
 /**
- * What a control inside a *body* cell should put in its `tabIndex`.
+ * What a control inside a body cell puts in its `tabIndex`. Internal: a
+ * consumer's own control needs nothing, the tab guards keep the body one stop.
  *
- * `-1` once cell selection is on, and this is what makes the promise of one tab
- * stop true. Without it the browser walks Tab into the checkbox of every
- * mounted row - a grid showing twenty rows would be twenty tab stops, and
- * scrolling would change how many. Enter or F2 steps into the cell instead,
- * which reaches a `-1` control perfectly well.
- *
- * Header controls are not covered: the header row is not part of cell
- * navigation, so its sort buttons and menus stay in the tab order, where they
- * are the only way to reach them.
- *
- * A custom cell renderer with a control in it wants the same:
- *
- * ```tsx
- * cell: ({ row }) => (
- *   <Button tabIndex={useCellControlTabIndex()} onClick={...}>Open</Button>
- * )
- * ```
+ * `-1` under cell selection: the control is reached by stepping into the cell
+ * with Enter or by the Tab walk within the row, never by the page's tab order,
+ * so a row does not add one tab stop per mounted row. `0` without it - there
+ * is no cursor to step in from, so the page's tab order is the only route.
  */
-export function useCellControlTabIndex(): 0 | -1 {
+export function useBodyControlTabIndex(): 0 | -1 {
   const { features } = useTMDataGridContext();
   return features.cellSelection ? -1 : 0;
 }

package/src/{tmdatagrid/components → components}/TMDataGrid.module.css

@@ -82,8 +82,14 @@
   /* The stacking ladder, stated once. Body cells sit at auto (0); everything
      sticky stacks over them in this order, and a sticky row crossing a sticky
      column takes the row's slot plus one. */
+  /* The focus ring is drawn inside the focused cell's own box, so the cell
+     takes a slot of its own - above the plain cells beside it, but under the
+     pinned lanes, which a scrolling row has to pass beneath ring and all. A
+     focused cell that is itself pinned goes above them instead, so its ring
+     stays whole while the rest of the row slides under it. */
+  --dg-z-focused-cell: 1;
   --dg-z-pinned-cell: 2;
-  --dg-z-focused-cell: 3;
+  --dg-z-pinned-focused-cell: 3;
   /* The pinned-row slot serves both sticky rows: the summary along the
      bottom and the entry block under the header. */
   --dg-z-pinned-row: 4;

package/src/{tmdatagrid/components → components}/TMDataGrid.tsx

@@ -7,16 +7,17 @@ import { TMDataGridDraftActions } from "./TMDataGridDraftActions";
 import { TMDataGridFilterPanel } from "./TMDataGridFilterPanel";
 import { TMDataGridFilterPills } from "./TMDataGridFilterPills";
 import { TMDataGridFooter } from "./TMDataGridFooter";
+import { TMDataGridMenu } from "./TMDataGridMenu";
 import { TMDataGridSearch } from "./TMDataGridSearch";
 import { TMDataGridTable } from "./TMDataGridTable";
 import {
-  TMDataGridColumnsButton,
   TMDataGridFilterButton,
   TMDataGridLoadingIndicator,
   TMDataGridSummaryCount,
   TMDataGridToolbar,
   TMDataGridToolbarSpacer,
 } from "./TMDataGridToolbar";
+import { TMDataGridExportPicker } from "./TMDataGridExportPicker";
 import {
   DEFAULT_TMDATAGRID_SIZE,
   SIZE_CONTROL_SIZE,
@@ -55,29 +56,15 @@ export type TMDataGridProps<TData extends RowData> = TMDataGridApi<TData> & {
   "data-testid"?: string;
 };
 
-/**
- * Root of the grid. Takes the object returned by `useTMDataGrid` - spread it -
- * and publishes it to the compound components below it:
- *
- * ```tsx
- * const grid = useTMDataGrid({ data, columns });
- *
- * <TMDataGrid {...grid}>
- *   <TMDataGrid.Toolbar>
- *     <TMDataGrid.SummaryCount />
- *     <TMDataGrid.Spacer />
- *     <TMDataGrid.ColumnsButton />
- *   </TMDataGrid.Toolbar>
- *   <TMDataGrid.Table />
- *   <TMDataGrid.Footer />
- * </TMDataGrid>
- * ```
- */
+// Documented on the `TMDataGrid` export below.
+// oxlint-disable-next-line react/only-export-components -- exported as the Object.assign compound `TMDataGrid`, which the rule cannot see as a component
 function TMDataGridRoot<TData extends RowData>({
   table,
   ui,
   edit,
   features,
+  filters,
+  exportOptions,
   labels,
   renderDetails,
   renderDetailsEstHeight,
@@ -100,6 +87,8 @@ function TMDataGridRoot<TData extends RowData>({
       ui,
       edit,
       features,
+      filters,
+      exportOptions,
       labels,
       renderDetails,
       renderDetailsEstHeight,
@@ -116,6 +105,8 @@ function TMDataGridRoot<TData extends RowData>({
       ui,
       edit,
       features,
+      filters,
+      exportOptions,
       labels,
       renderDetails,
       renderDetailsEstHeight,
@@ -141,10 +132,33 @@ function TMDataGridRoot<TData extends RowData>({
       >
         {children}
       </div>
+      {/* Portaled by Mantine, so outside the root element; inside the
+          provider, since it reads the grid. */}
+      <TMDataGridExportPicker />
     </TMDataGridContextProvider>
   );
 }
 
+/**
+ * Root of the grid. Takes the object returned by `useTMDataGrid` - spread it -
+ * and publishes it to the compound components below it:
+ *
+ * ```tsx
+ * const grid = useTMDataGrid({ data, columns });
+ *
+ * <TMDataGrid {...grid}>
+ *   <TMDataGrid.Toolbar>
+ *     <TMDataGrid.SummaryCount />
+ *     <TMDataGrid.Spacer />
+ *     <TMDataGrid.Menu>
+ *       <TMDataGrid.Menu.Columns />
+ *     </TMDataGrid.Menu>
+ *   </TMDataGrid.Toolbar>
+ *   <TMDataGrid.Table />
+ *   <TMDataGrid.Footer />
+ * </TMDataGrid>
+ * ```
+ */
 export const TMDataGrid = Object.assign(TMDataGridRoot, {
   Toolbar: TMDataGridToolbar,
   Spacer: TMDataGridToolbarSpacer,
@@ -152,7 +166,7 @@ export const TMDataGrid = Object.assign(TMDataGridRoot, {
   LoadingIndicator: TMDataGridLoadingIndicator,
   Search: TMDataGridSearch,
   DraftActions: TMDataGridDraftActions,
-  ColumnsButton: TMDataGridColumnsButton,
+  Menu: TMDataGridMenu,
   FilterButton: TMDataGridFilterButton,
   Table: TMDataGridTable,
   Footer: TMDataGridFooter,
@@ -163,6 +177,9 @@ export const TMDataGrid = Object.assign(TMDataGridRoot, {
    * rendered outside `<TMDataGrid>` - a page header, for instance.
    */
   FilterPills: TMDataGridFilterPills,
-  /** Rendered by `TMDataGrid.ColumnsButton`; exported for custom layouts. */
+  /**
+   * The column chooser as plain controls, for a Popover, a Drawer or an
+   * inline layout; `TMDataGrid.Menu.Columns` is the same thing as menu items.
+   */
   ColumnsPanel: TMDataGridColumnsPanel,
 });