@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/docs/testing.md

@@ -0,0 +1,309 @@
+# Testing
+
+The grid publishes a fixed set of roles, ARIA attributes and `data-*` hooks so
+that a consumer's suite can be written against structure rather than against
+copy or class names. Everything on this page is supported. Anything else in the
+DOM is internal and may change without notice.
+
+> Renaming or dropping anything on this page is a breaking change, so it moves
+> only with a major version.
+
+## Selector attributes
+
+The grid publishes three kinds of selector, and no `data-testid` of its own:
+
+- `data-dg-part` - what an element is (`"row"`, `"filter-button"`)
+- `data-row-id` and `data-column-id` - which one, using your own ids
+- roles and ARIA - the same thing a screen reader reads
+
+`data-testid` is left to your suite, whose `testIdAttribute` may be `data-qa` or
+`data-cy` rather than `data-testid`. The one exception is
+`<TMDataGrid data-testid>`, which sets the value you pass.
+
+## Naming a grid
+
+Parts repeat across grids on the same page. Name the grid and scope through it:
+
+```tsx
+<TMDataGrid {...grid} data-testid="orders">
+  <TMDataGrid.Table<Order> aria-label="Orders" />
+</TMDataGrid>
+```
+
+```ts
+const orders = page.getByTestId("orders");
+await expect(orders.locator('[data-dg-part="row"][data-row-id="42"]')).toBeVisible();
+```
+
+`data-testid` and `id` go on the root element (which also carries
+`data-dg-root`); `aria-label` (or `aria-labelledby`) goes on
+`TMDataGrid.Table`, because the accessible name belongs to the element carrying
+the `grid` role.
+
+## Structure
+
+| Element | Role | Attributes |
+| --- | --- | --- |
+| Root | - | `data-dg-root`, `data-size` |
+| Grid | `table`, or `grid` under cell selection | `aria-rowcount`, `aria-colcount`, `aria-busy`, `data-dg-row-count` |
+| Header row | `row` | `aria-rowindex` |
+| Header cell | `columnheader` | `data-dg-part="header"`, `data-column-id`, `aria-sort`, `data-active` |
+| Body row | `row` | `data-dg-part="row"`, `data-row-id`, `aria-rowindex`, `data-selected`, `data-highlighted`, `data-grouped`, `data-depth`, `data-pinned`, `data-deleted`, `data-dirty`, `data-draft`, `data-new`, `data-striped` |
+| Body cell | `cell`, or `gridcell` under cell selection | `data-row-id`, `data-column-id`, `data-align`, `data-editing`, `data-dirty`, `data-invalid`, `data-focused`, `data-selected` |
+
+**The role changes with cell selection.** `cellSelection` turns the grid's
+`table` into a `grid` and every `cell` into a `gridcell`, so a suite written on
+`getByRole("cell")` breaks when the feature is switched on. Query cells by their
+coordinates instead:
+
+```ts
+const cell = orders.locator('[data-row-id="42"][data-column-id="total"]');
+```
+
+Body cells carry no `data-dg-part`; the coordinate pair identifies them.
+
+## Parts
+
+Row and column ids come from your data (`getRowId` and the column definitions),
+so a part that repeats is addressed by adding the coordinate.
+
+### Whole-grid
+
+| `data-dg-part` | What it is |
+| --- | --- |
+| `toolbar` | The toolbar row |
+| `summary-count` | The visible/total count |
+| `loading` | The toolbar spinner |
+| `search`, `search-clear` | Quick search input and its ✕ |
+| `filter-button` | The funnel toggle |
+| `filter-panel` | The panel of filter rows, wherever it is rendered |
+| `filter-popup`, `filter-sidebar` | The surface holding it, under `filters.surface` |
+| `filter-panel-close` | The surface's ✕; absent on a hand-placed panel |
+| `filter-add`, `filter-clear-all` | The panel's footer buttons |
+| `header-filter-row` | The header filter row, under `filters.inHeader` |
+| `filter-pills` | The active-filter pill group |
+| `menu-button` | The burger, `TMDataGrid.Menu` |
+| `columns-panel`, `columns-search` | The column chooser panel, and the search box in the panel or in `TMDataGrid.Menu.Columns` |
+| `columns-toggle-all`, `columns-reset` | Show/hide all and Reset layout, in the panel or in the menu |
+| `footer` | The pager row |
+| `page-size`, `page-range`, `page-number`, `page-prev`, `page-next` | The pager |
+| `summary-row` | The footer summary row |
+| `pinned-top`, `pinned-bottom` | The pinned-row edge blocks |
+| `select-all` | The header select-all checkbox |
+| `details-toggle-all` | Expand/collapse every detail panel |
+| `save-all`, `discard-all` | `TMDataGrid.DraftActions`. `save-all` carries `data-draft-count` - the rows the save will send |
+| `editor-confirm`, `editor-cancel` | `cellConfirm`'s ✓ and ✕ |
+| `editor-input` | The input inside a built-in editor |
+| `sort-index` | A column's position in a multi-column sort |
+| `tab-guard` | The body's tab stop under [cell selection](/docs/cell-selection); `data-guard` is `leading` (before the rows) or `trailing` (after them). Zero-size, and focusing one puts the cursor on a cell |
+
+### Keyed by `data-row-id`
+
+| `data-dg-part` | What it is |
+| --- | --- |
+| `row` | A body row, pinned or not. A committed new row is one of them, marked `data-new` |
+| `entry-row` | An entry row being typed into. Carries `data-new`, and `data-committed` / `data-draft` once committed, which is where a committed row stays under `editing.newRowsSticky`. Its cells carry `data-column-id` and, on a failed ✓, `data-invalid` |
+| `details` | A row's detail panel |
+| `select-row` | Its selection checkbox |
+| `details-toggle`, `group-toggle` | Its detail and tree chevrons |
+| `edit-row`, `delete-row` | The edit lane, idle. `edit-row` also reopens an entered new row |
+| `save-row`, `cancel-row` | The edit lane's Save and Cancel on an open row |
+| `row-state` | The draft store's change marker; `data-state` is `new`, `edited` or `deleted` |
+| `revert-row` | Drops a committed row's draft |
+| `restore-row` | Undo a deletion mark |
+| `confirm-new-row`, `discard-new-row` | An entry row's ✓ (commit) and ✕ |
+| `open-rows-note` | `DraftActions`' count of rows still open. Carries `data-open-count`; absent while there are none |
+
+### Keyed by `data-column-id`
+
+| `data-dg-part` | What it is |
+| --- | --- |
+| `header` | A column header |
+| `header-sort`, `header-menu`, `header-filter` | Its three action buttons. `header-filter` is absent under `filters.inHeader`, where the control below is the indicator |
+| `header-filter-cell`, `header-filter-operator` | One column's header filter control and its operator button |
+| `filter-row` | One row of the filter panel |
+| `filter-pill` | One active-filter pill; its ✕ is the only button inside it |
+| `columns-toggle` | The checkbox of one column, in the panel or in the menu |
+
+### Keyed by both
+
+| `data-dg-part` | What it is |
+| --- | --- |
+| `editor` | An open cell editor |
+
+Within a filter row the three controls are `filter-column`,
+`filter-operator` and `filter-value` (or `filter-value-from` /
+`filter-value-to` for `between`).
+
+A column declaring `meta.filter.control` or `meta.edit.editor` renders your component
+in that slot, so `filter-value` and `editor-input` cover the built-ins only.
+`filter-row` and `editor` still apply; scope your own queries through them.
+
+`editor-input` is also where the grid puts the caret when an editor opens. An
+editor that does not publish it is focused on the first focusable element inside
+its `editor` instead, so a custom editor needs the attribute only to name which
+of several inputs the caret should land in.
+
+Every icon-only control also carries an `aria-label` drawn from `labels`. Those
+are translated, so they make brittle selectors. Prefer the parts above unless
+your grid runs in one language.
+
+## Virtualization
+
+The grid is always virtualized: only the rows in the viewport plus overscan are
+in the DOM. A row at index 500 has no element, and Playwright cannot scroll to
+what it cannot find.
+
+**Count rows off the grid, not off the DOM.** `aria-rowcount` includes every
+header row - stacked column groups and the `filters.inHeader` row among them -
+and the summary row, so how many it adds is a function of the grid's
+configuration. `data-dg-row-count` counts the body rows alone: the current page
+under pagination, or everything the filters left otherwise. Assert on that one.
+
+```ts
+const grid = orders.getByRole("table");
+await expect(grid).toHaveAttribute("data-dg-row-count", "3");
+```
+
+**Reach a row by narrowing to it.** Filtering or searching is faster and more
+stable than scrolling:
+
+```ts
+await orders.locator('[data-dg-part="search"]').fill("Nordkvist");
+await expect(orders.locator('[data-row-id="42"]').first()).toBeVisible();
+```
+
+**Or scroll to it.** When the row must be reached in place, such as when testing
+the scroll itself, `scrollToRow` moves the virtualizer:
+
+```ts
+const found = grid.scrollToRow({ rowId: "42", align: "center" });
+```
+
+It returns `false` when the row is not in the current view (filtered out, on
+another page, or an unknown id) and scrolls nothing. From a Playwright test it
+has to be called through the page, since the API lives in React:
+
+```ts
+await page.evaluate(() => window.__ordersGrid.scrollToRow({ rowId: "42" }));
+```
+
+which requires the app to expose the grid on `window`. Narrowing needs no such
+hook.
+
+## Waiting
+
+`meta.loading` sets `aria-busy` on the grid whether or not the body has rows, so
+a refetch over existing rows is still visible to a test:
+
+```ts
+await expect(grid).toHaveAttribute("aria-busy", "true");
+await expect(grid).not.toHaveAttribute("aria-busy");
+```
+
+Quick search debounces (250 ms by default, `debounce` on `TMDataGrid.Search`).
+Assert on `data-dg-row-count` rather than adding a timeout. Playwright retries
+the assertion until the debounce lands.
+
+## A page object
+
+A helper class wraps the parts:
+
+```ts
+import { type Locator, type Page, expect } from "@playwright/test";
+
+type PartKey = { rowId?: string; columnId?: string };
+
+export class DataGrid {
+  readonly root: Locator;
+  readonly grid: Locator;
+
+  constructor(page: Page, testId: string) {
+    this.root = page.getByTestId(testId);
+    this.grid = this.root.getByRole("table");
+  }
+
+  /** A named part, narrowed by row or column when the part repeats. */
+  part(name: string, key: PartKey = {}): Locator {
+    const selector =
+      `[data-dg-part="${name}"]` +
+      (key.rowId === undefined ? "" : `[data-row-id="${key.rowId}"]`) +
+      (key.columnId === undefined ? "" : `[data-column-id="${key.columnId}"]`);
+    return this.root.locator(selector);
+  }
+
+  cell({ rowId, columnId }: { rowId: string; columnId: string }): Locator {
+    return this.root.locator(
+      `[data-row-id="${rowId}"][data-column-id="${columnId}"]`,
+    );
+  }
+
+  async search(text: string): Promise<void> {
+    await this.part("search").fill(text);
+  }
+
+  async sortBy(columnId: string): Promise<void> {
+    await this.part("header-sort", { columnId }).click();
+  }
+
+  async filterBy({
+    columnId,
+    value,
+  }: {
+    columnId: string;
+    value: string;
+  }): Promise<void> {
+    await this.part("filter-button").click();
+    await this.part("filter-row", { columnId })
+      .locator('[data-dg-part="filter-value"]')
+      .fill(value);
+  }
+
+  async toggleColumn(columnId: string): Promise<void> {
+    await this.part("menu-button").click();
+    await this.part("columns-toggle", { columnId }).click();
+  }
+
+  async expectRowCount(count: number): Promise<void> {
+    await expect(this.grid).toHaveAttribute(
+      "data-dg-row-count",
+      String(count),
+    );
+  }
+
+  async expectSettled(): Promise<void> {
+    await expect(this.grid).not.toHaveAttribute("aria-busy");
+  }
+}
+```
+
+```ts
+test("filters to one employee", async ({ page }) => {
+  const grid = new DataGrid(page, "employees");
+  await page.goto("/employees");
+  await grid.expectSettled();
+
+  await grid.filterBy({ columnId: "lastName", value: "Nordkvist" });
+  await grid.expectRowCount(1);
+  await expect(grid.cell({ rowId: "42", columnId: "city" })).toHaveText(
+    "Stockholm",
+  );
+});
+```
+
+## React Testing Library
+
+Under jsdom there is no layout, so the virtualizer mounts a handful of rows
+whatever the data says. Assert on the grid's own counts rather than on the
+number of row elements:
+
+```tsx
+const rowCount = Number(
+  screen.getByRole("table").getAttribute("data-dg-row-count"),
+);
+expect(rowCount).toBe(3);
+```
+
+Mantine's transitions never settle under jsdom, so a Popover's dropdown mounts
+empty, including the filter and column panels. Render inside
+`<MantineProvider env="test">`.

package/docs/toolbar.md

@@ -0,0 +1,161 @@
+# Toolbar
+
+The toolbar is a flex row. Your own buttons are children of it, beside the
+built-in ones; there is no slots API and no `actions` prop.
+
+```tsx
+<TMDataGrid.Toolbar>
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer />
+  <TMDataGrid.LoadingIndicator />
+  <Button size="xs" variant="light" onClick={exportAll}>
+    Export
+  </Button>
+  <TMDataGrid.FilterButton />
+  <TMDataGrid.Menu>
+    <TMDataGrid.Menu.Columns />
+  </TMDataGrid.Menu>
+</TMDataGrid.Toolbar>
+```
+
+`TMDataGrid.Spacer` pushes everything after it to the right.
+`TMDataGrid.Menu` is the burger; it holds the column chooser here, and anything else you put in it.
+See [Grid menu](/docs/menu).
+
+```demo
+file: customization/ToolbarComposition.tsx
+extraSources: data/employeeColumns.tsx
+```
+
+Only the parts you render exist. A grid with no `Toolbar` has no toolbar; a
+toolbar with only `Search` has only a search box.
+
+## Style props
+
+`TMDataGrid.Toolbar` and `TMDataGrid.Spacer` take Mantine's `BoxProps`: the style props (`mb`, `px`, `h`, `hiddenFrom`, …), `className`, `style` and `mod`, set on the element itself.
+`withBottomBorder` draws a 1px line under the toolbar in the theme's default border colour, the same line the header draws under itself.
+It defaults to `false`.
+
+```tsx
+<TMDataGrid.Toolbar withBottomBorder px="sm">
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer hiddenFrom="sm" />
+  <TMDataGrid.FilterButton />
+</TMDataGrid.Toolbar>
+```
+
+`TMDataGrid.Footer`, `TMDataGrid.FilterPanel`, `TMDataGrid.FilterPills` and `TMDataGrid.ColumnsPanel` take the same `BoxProps`; see [Components](/docs/components).
+
+## The built-in parts
+
+| Component | Shows |
+| --- | --- |
+| `TMDataGrid.Search` | The [quick search](/docs/quick-search) input |
+| `TMDataGrid.FilterButton` | Opens the [filter panel](/docs/filtering), with the active count |
+| `TMDataGrid.Menu` | The burger: a [menu](/docs/menu) you fill; `TMDataGrid.Menu.Columns` is the column chooser as items |
+| `TMDataGrid.SummaryCount` | Visible rows out of total, or the count alone where there is no total to compare it against |
+| `TMDataGrid.LoadingIndicator` | A spinner while `meta.loading` |
+| `TMDataGrid.Spacer` | Pushes what follows to the right |
+| `TMDataGridDraftActions` | Save and Discard for the [draft store](/docs/editing#the-draft-store) |
+
+Each renders nothing when its feature is off, so a read-only grid needs no
+conditionals in the toolbar: `FilterButton` under `enableColumnFilters: false`
+renders nothing at all.
+`TMDataGrid.Menu` is the exception, since it cannot see what its children render; see [Grid menu](/docs/menu).
+
+## Buttons of your own
+
+A button that acts on the grid reads it from context:
+
+```tsx
+import { useTMDataGridContext } from "@jielga/tmdatagrid";
+
+function ClearFiltersButton() {
+  const { table } = useTMDataGridContext();
+  return (
+    <Button size="xs" onClick={() => table.resetColumnFilters()}>
+      Clear filters
+    </Button>
+  );
+}
+```
+
+Anything rendered inside `TMDataGrid` can call it. It returns
+`{ table, ui, features, filters, exportOptions, labels, controlSize, resetSettings }`.
+
+An export button uses `useTMDataGridExport`, which hands back the export as click handlers:
+
+```tsx
+import { useTMDataGridExport } from "@jielga/tmdatagrid";
+
+function ExportButton() {
+  const { exportAll } = useTMDataGridExport();
+  return (
+    <Button size="xs" onClick={() => void exportAll()}>
+      Export
+    </Button>
+  );
+}
+```
+
+It writes every filtered row, whatever the cell selection is or whether cell selection is on at all.
+The format, the file name and the selected-rows variant are on [Export](/docs/export).
+
+### Hide a button when its feature is off
+
+The built-in parts disappear when their feature is off. Your own can use the
+same checks instead of re-deriving them:
+
+```tsx
+import { getGridCapabilities, useTMDataGridContext } from "@jielga/tmdatagrid";
+
+function ExportButton() {
+  const { table, features } = useTMDataGridContext();
+  const { canFilterAny } = getGridCapabilities(table, features);
+
+  if (!canFilterAny) return null;
+  // …
+}
+```
+
+| Field | True when |
+| --- | --- |
+| `canSortAny` | At least one leaf column can be sorted |
+| `canFilterAny` | At least one leaf column can be filtered |
+| `canHideAny` | At least one leaf column can be hidden |
+| `canPinAny` | At least one leaf column can be pinned |
+| `canReorderAny` | At least one leaf column can be moved |
+| `canGroupAny` | At least one leaf column can be grouped on |
+| `canSelectRows` | `enableRowSelection` is not `false` and the mode is not `"highlight"` |
+| `canPaginate` | Paging is configured. See [`isPagingActive`](/docs/pagination#grouping) for whether it is slicing anything |
+| `canSearch` | At least one leaf column takes part in the quick search |
+
+`getColumnCapabilities(column, features)` returns the same for one column, as
+`canSort`, `canFilter`, `canHide`, `canPin`, `canResize`, `canReorder` and
+`canGroup`.
+
+### Reading options reactively
+
+`features` is re-derived from the options object on every render, and both
+capability helpers take it alongside the table or column. A bare
+`column.getCanSort()` is memoized against a column identity that survives an
+options change, so a grid whose `enableSorting` turned `false` would keep
+rendering sort indicators; `features` is the value that changes.
+
+Read state through TanStack Store's
+[`useSelector(table.store, …)`](https://tanstack.com/store/latest/docs/framework/react/reference)
+and options through `features`, rather than calling methods on a long-lived
+object.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `TMDataGrid.Toolbar` | Component | `children`, `withBottomBorder`, Mantine `BoxProps` | `withBottomBorder: false` | The flex row above the grid. Style props set on the row. |
+| `TMDataGrid.Spacer` | Component | Mantine `BoxProps` | – | Pushes what follows to the right. |
+| `TMDataGrid.FilterButton` | Component | – | – | Opens the filter panel, with an active count. |
+| `TMDataGrid.Menu` | Component | `children` | – | The burger and its dropdown. See [Grid menu](/docs/menu). |
+| `useTMDataGridContext` | Hook | `() => TMDataGridContextValue` | – | `{ table, ui, features, labels, controlSize, resetSettings }`. |
+| `getGridCapabilities` | Export | `(table, features) => TMDataGridCapabilities` | – | What this grid can do. Reactive to option changes. |
+| `getColumnCapabilities` | Export | `(column, features) => TMDataGridColumnCapabilities` | – | The same for one column. |
+| `readFeatureFlags` | Export | `(options) => TMDataGridFeatureFlags` | – | Derives the flags from an options object. |