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

package/docs/grouping.md

@@ -56,7 +56,7 @@ grouped columns to the front. Note that the kept column's data cells render as
 TanStack's grouped-cell placeholder - blank - with the value only on group
 rows, so it repeats what the tree lane already shows and cannot be typed into.
 To set the grouped field on a new row, seed it through `edit.addRow(values)` -
-see [Editing](/docs/editing#adding-and-deleting-rows).
+see [Editing](/docs/editing#adding-rows).
 
 ## Aggregation
 
@@ -114,10 +114,10 @@ so it does not fire `onRowClick`, cannot be highlighted, cannot be
 `rowStyle` and `rowClassName` are the exception: they are called for group rows too, with that same child's record as `original`.
 Guard a callback that reads `original` with `row.getIsGrouped()`, and set `--dg-row-group-bg` to colour the group rows themselves.
 
-`data-grouped` is published on every row, `"true"` on group rows and `"false"`
-on the rest, so match the value - `[data-grouped="true"]` - rather than the
-bare attribute. `data-depth` carries the nesting level, and
-`--dg-row-group-bg` sets a group row's background.
+`data-grouped` is present, with the value `"true"`, only on group rows, so
+`[data-grouped]` and `[data-grouped="true"]` are equivalent. `data-depth`
+carries the nesting level, and `--dg-row-group-bg` sets a group row's
+background.
 
 ## Grouping and pagination
 
@@ -161,5 +161,5 @@ server-side can set `enableGrouping: true` alongside `manualGrouping: true`. See
 | `getGroupDataRows` | Export | `(row) => Row[]` | – | Every record under a group row, at any depth. |
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything. `false` while grouped. |
 | `--dg-row-group-bg` | CSS variable | colour | Themed | Group row background. |
-| `data-grouped` | Data attribute | `"true" \| "false"` | – | `"true"` on group rows. Published on every row. |
+| `data-grouped` | Data attribute | `"true"` | – | `"true"` on group rows. Absent on the rest. |
 | `data-depth` | Data attribute | `number` | – | Nesting level, on every row. |

package/docs/row-styling.md

@@ -105,13 +105,13 @@ it without a callback:
 | `data-selected` | Selected rows |
 | `data-selected-bg` | Selected rows that also take the background |
 | `data-highlighted` | The highlighted row |
-| `data-grouped` | Every row: `"true"` on group rows, `"false"` on the rest |
+| `data-grouped` | Group rows |
 | `data-depth` | Every row. The nesting level |
 | `data-context-menu` | The row whose context menu is open |
 | `data-row-id` | Every row. Its id, which [tests](/docs/testing) key off |
 
-The state attributes are published as `"true"` or `"false"`, so match the
-value; the bare attribute selector matches every row:
+The state attributes are present, with the value `"true"`, only on the rows
+they apply to, so the bare attribute and the value match the same rows:
 
 ```css
 [data-dg-part="row"][data-grouped="true"] {

package/docs/styling.md

@@ -50,7 +50,7 @@ The wrapper components - `Toolbar`, `Spacer`, `Footer`, `FilterPanel`, `FilterPi
 | `--dg-row-height` | From `size` | Row height. Prefer `meta.rowHeight` - the virtualizer needs the number. |
 | `--dg-header-height` | From `size` | Header row height |
 | `--dg-summary-height` | From `size` | [Summary row](/docs/summary-row) height |
-| `--dg-entry-height` | From `size` | The sticky [entry block](/docs/editing#adding-and-deleting-rows) |
+| `--dg-entry-height` | From `size` | The sticky [entry block](/docs/editing#adding-rows) |
 | `--dg-font-size` | From `size` | Cell and header font size |
 | `--dg-padding` | From `size` | Horizontal cell padding. The generated lanes are excluded: they are fixed 36px tracks that centre their control. |
 | `--dg-radius` | `--mantine-radius-md` | The frame's corner radius. `0` squares the grid off. The root clips its overflow, so the header and the last row follow it. |

package/docs/testing.md

@@ -62,6 +62,17 @@ const cell = orders.locator('[data-row-id="42"][data-column-id="total"]');
 
 Body cells carry no `data-dg-part`; the coordinate pair identifies them.
 
+**State attributes are present only while they apply.** A boolean attribute
+such as `data-selected`, `data-new` or `data-invalid` is rendered with the
+value `"true"` while its state holds and omitted otherwise, so the bare
+attribute and the value match the same elements, and the negative is the
+absence:
+
+```ts
+const drafts = orders.locator('[data-dg-part="row"][data-draft]');
+await expect(row).not.toHaveAttribute("data-deleted");
+```
+
 ## Parts
 
 Row and column ids come from your data (`getRowId` and the column definitions),
@@ -264,6 +275,49 @@ export class DataGrid {
     await this.part("columns-toggle", { columnId }).click();
   }
 
+  /** The entry row opened by `edit.addRow()`; `data-row-id` is its temp id. */
+  entryRow(): Locator {
+    return this.part("entry-row");
+  }
+
+  /** Types into the 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();
+  }
+
+  /** Presses Save in `TMDataGrid.DraftActions` and waits for the store to empty. */
+  async saveDrafts(): Promise<void> {
+    await this.part("save-all").click();
+    await expect(this.part("save-all")).toHaveAttribute("data-draft-count", "0");
+  }
+
+  /** Finds a row the test added by a value unique to it, since the grid does
+   *  not know the id the app gave the row. Retries until the app has put the
+   *  row in `data`. */
+  async expectRowAdded(
+    uniqueValue: string,
+    cells: Record<string, string>,
+  ): Promise<void> {
+    await this.search(uniqueValue);
+    await this.expectRowCount(1);
+    const row = this.part("row");
+    for (const [columnId, text] of Object.entries(cells)) {
+      await expect(row.locator(`[data-column-id="${columnId}"]`)).toHaveText(
+        text,
+      );
+    }
+    await this.search("");
+  }
+
   async expectRowCount(count: number): Promise<void> {
     await expect(this.grid).toHaveAttribute(
       "data-dg-row-count",
@@ -291,6 +345,133 @@ test("filters to one employee", async ({ page }) => {
 });
 ```
 
+## Editing
+
+### Adding a row
+
+[`edit.addRow()`](/docs/editing) opens an entry row, `data-dg-part="entry-row"`,
+keyed by a temporary id (`__new__1`, `__new__2`, …). Its editors are `editor`
+parts keyed by that id and the column. What ✓ does with the row depends on
+`editing.draft`:
+
+| Step | Without `draft` | With `draft: true` |
+| --- | --- | --- |
+| `addRow()` | `entry-row[data-row-id="__new__1"]` | Same |
+| ✓ fails validation | The entry row stays; the failing cells carry `data-invalid` | Same |
+| ✓ (`confirm-new-row`) | The entry row is removed and the temp id is gone. `onRowAdd` receives the values, and the row exists again only once your app puts it in `data`, under the id your `getRowId` returns | The row becomes a body row, still keyed by the temp id: `row[data-row-id="__new__1"][data-new="true"][data-draft="true"]`, with `row-state[data-state="new"]` in its lane and `save-all[data-draft-count]` counting it |
+| Save (`save-all`) | - | As ✓ without `draft`: the temp id is gone, and the row comes back through `data` under your id |
+
+The grid never learns which id your app gave the row, so once `onRowAdd` or
+`saveDrafts` has run, the row cannot be addressed by id. Find it by its content
+instead: narrow the grid to a value unique to the row, assert that one row is
+left, and read that row's cells. The row-count assertion is also the wait,
+since it retries until the app has put the row in `data`:
+
+```ts
+test("adds an employee", async ({ page }) => {
+  const grid = new DataGrid(page, "employees");
+  await page.goto("/employees");
+  await grid.expectSettled();
+
+  // The app's own button, calling edit.addRow()
+  await page.getByRole("button", { name: "Add row" }).click();
+  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);
+  await grid.expectRowAdded("Nordkvist-4711", {
+    name: "Nordkvist-4711",
+    city: "Stockholm",
+  });
+});
+```
+
+Use a value no other row has, such as a name with a run id in it, so that the
+search leaves one row. If the grid has no quick search, narrow with `filterBy`
+on a column instead.
+
+Under `draft: true` the temp id stays valid until Save, so the committed row is
+asserted directly, and the content-based check applies after the save:
+
+```ts
+await grid.commitEntryRow(tempId);
+const row = grid.part("row", { rowId: tempId });
+await expect(row).toHaveAttribute("data-new", "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);
+await grid.expectRowAdded("Nordkvist-4711", { city: "Stockholm" });
+```
+
+Under `newRowsSticky: true` the committed row stays in the entry block instead,
+as `entry-row[data-row-id="__new__1"][data-committed="true"]`, outside
+`data-dg-row-count`, until the save.
+
+A ✓ that fails validation keeps the entry row open, with `data-invalid` on the
+failing cells:
+
+```ts
+await grid.commitEntryRow(tempId);
+await expect(grid.entryRow()).toHaveCount(1);
+await expect(
+  grid.entryRow().locator('[data-column-id="email"]'),
+).toHaveAttribute("data-invalid", "true");
+```
+
+### Changing a row
+
+Without `draft`, a commit goes to `onCommit` and the grid keeps nothing of it, so
+the assertion is the cell's text once your app has applied the change. Under
+`draft: true` the change stays in the grid until Save, marked on the cell, the
+row and the lane:
+
+```ts
+const cell = grid.cell({ rowId: "42", columnId: "salary" });
+await cell.dblclick();
+await grid.fillRow("42", { salary: "52000" });
+await page.keyboard.press("Enter");
+
+// Without draft: the app applied it
+await expect(cell).toHaveText("52 000");
+
+// Under draft: the grid holds it
+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",
+);
+```
+
+In row mode, `edit-row` opens the row, `save-row` commits it and `cancel-row`
+discards it; `fillRow` reaches the open row's editors the same way.
+
+### Deleting a row
+
+`delete-row` calls `onRowDelete` at once, or marks the row under `draft: true`:
+
+```ts
+const before = Number(await grid.grid.getAttribute("data-dg-row-count"));
+await grid.part("delete-row", { rowId: "42" }).click();
+
+// Without draft: the app removed it from data
+await grid.expectRowCount(before - 1);
+
+// Under draft: marked until Save, and Restore undoes the mark
+await expect(grid.part("row", { rowId: "42" })).toHaveAttribute("data-deleted", "true");
+await grid.part("restore-row", { rowId: "42" }).click();
+```
+
+Assert a deletion on `data-dg-row-count`, not on the row's element: a row
+outside the viewport has no element either, so `toHaveCount(0)` passes for it
+whether or not it was deleted.
+
 ## React Testing Library
 
 Under jsdom there is no layout, so the virtualizer mounts a handful of rows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.0.0-beta.21",
+  "version": "2.0.0-beta.23",
   "description": "A React data grid built on TanStack Table v9 and Mantine - always virtualized, with resizable, reorderable, sortable, filterable, hideable and pinnable columns.",
   "license": "MIT",
   "type": "module",

package/skills/appearance/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/styling.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/toolbar.md'

package/skills/cell-selection/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/cell-selection.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/cellNavigation.ts'

package/skills/columns/SKILL.md

@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/columns.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/column-layout.md'

package/skills/data/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/pagination.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/scrolling.md'

package/skills/editing/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/editing.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/query-builder.md'
@@ -385,8 +385,9 @@ row it reaches.
 `deleteRow`, `getForm`, and `store` for `useSelector` (an example is under
 [Submitting an outer form](#high-submitting-an-outer-form-while-the-grid-holds-a-draft)).
 `edit.store` publishes each open or committed row's drafted values as
-`rows[rowId].values`, which is what a computed cell or a cross-row check reads
-- `useTMDataGridContext()` reaches the engine from inside a cell renderer.
+`rows[rowId].values`, which is what a cross-row check reads. A `cell`
+renderer needs no lookup: its `row.original` is already the row as shown, and
+`getRowValues(rowId)` is the same row for a handler with no cell context.
 Every member with its signature, the gates, `isColumnEditable`, `deactivate`,
 and the `edit.store` shape are in
 [references/editing-api.md](references/editing-api.md#the-edit-engine).

package/skills/editing/references/common-mistakes.md

@@ -187,24 +187,23 @@ A refused value leaves the row open carrying its errors and the call resolves `f
 
 Source: `packages/tmdatagrid/src/core/editEngine.ts` (`begin`, `writeFields`).
 
-## MEDIUM A computed column frozen while a row is edited
+## MEDIUM Reading an open row's values off `row.original` outside a cell
 
-A held draft is displayed by the column that owns the field. A column computed
-from other fields - `accessorFn` or `display` - reads `row.original`, which is
-`data`, so it keeps showing the saved record while the values it derives from
-are being typed.
+Inside a `cell` renderer, `row.original` and `getValue()` are the row as
+shown: the open form's values while the row is edited, the committed draft
+after ✓, and `data` otherwise - a computed column follows the draft as it is
+typed, and a button in a cell sends the draft the user sees. Outside it, the
+row callbacks (`onRowClick`, `renderRowContextMenu`, `rowClassName`) and any
+code holding a row id see `data`, or the committed draft, and never an open
+form's values.
 
-Correct: read the drafted row from `edit.store` inside the cell renderer:
+Correct: reach the row as shown by id:
 
 ```tsx
-function useDraftedRow(rowId: string, original: Product): Product {
-  const { edit } = useTMDataGridContext();
-  const values = useSelector(edit.store, (state) => state.rows[rowId]?.values);
-  return (values as Product | undefined) ?? original;
-}
+const shown = grid.edit.getRowValues(row.id) ?? row.original;
 ```
 
-Source: `packages/tmdatagrid/docs/editing.md` (Draft lifetime).
+Source: `packages/tmdatagrid/docs/editing.md` (How a draft renders).
 
 ## MEDIUM Reading a commit's result as the saved value
 

package/skills/editing/references/editing-api.md

@@ -72,6 +72,8 @@ path, which may be dotted.
 | `isColumnEditable` | `(column) => boolean` | The column's half alone, with no row in hand: it maps to a field, `editing.columns` lists it when that is set, and `meta.edit.enabled` is not `false`. |
 | `canDeleteRows` | `() => boolean` | Whether the delete control should be shown. |
 | `getForm` | `(rowId) => TMDataGridRowEditForm \| undefined` | The open row's live `FormApi`; `undefined` for a committed row. |
+| `getRowValues` | `(rowId) => TData \| undefined` | The row as shown: the open form's values, else the committed draft, else the `data` value. `undefined` for an unknown row. |
+| `getRows` | `() => ReadonlyArray<TMDataGridEditRowSnapshot>` | Every row as shown, from the core row model: drafts overlaid, entry rows appended, deletion-marked rows included and flagged `deleted`. |
 | `state` | `TMDataGridEditState` | Snapshot, for reads outside React. |
 | `store` | `Store<TMDataGridEditState>` | For `useSelector`. |
 

package/skills/filtering/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/filtering.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/quick-search.md'

package/skills/getting-started/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/getting-started.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/anatomy.md'

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/grouping.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/summary-row.md'
@@ -90,8 +90,8 @@ would pass a row that looks real but is the wrong one. Group rows therefore:
   as `original`, so guard a callback reading `original` with
   `row.getIsGrouped()` and colour the group rows with `--dg-row-group-bg`
 - carry `data-grouped="true"` and `data-depth`, with `--dg-row-group-bg`
-  behind them. `data-grouped` is on every row, `"true"` or `"false"`, so match
-  the value rather than the bare attribute
+  behind them. `data-grouped` is present only on group rows, so
+  `[data-grouped]` and `[data-grouped="true"]` are equivalent
 
 A group row's checkbox selects every record under it at any depth, including
 records inside collapsed sub-groups, showing a tick once all are selected and a
@@ -273,7 +273,7 @@ Source: `packages/tmdatagrid/docs/grouping.md` (Server-side grids).
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything. `false` while grouped. |
 | `--dg-row-group-bg` | CSS variable | colour | Themed | Group row background. |
 | `--dg-summary-height` | CSS variable | length | From `size` | Height of the summary row. |
-| `data-grouped` · `data-depth` | Data attributes | – | – | `"true"` on group rows (published on every row), and the nesting level on every row. |
+| `data-grouped` · `data-depth` | Data attributes | – | – | `"true"` on group rows (absent on the rest), and the nesting level on every row. |
 
 See also: the `rows` skill for selection and the details lane, and the `data`
 skill for the pager grouping suspends.

package/skills/options/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/use-tm-data-grid.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-selection.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-interaction.md'
@@ -211,8 +211,9 @@ are not striped.
 Rows carry `data-selected`, `data-selected-bg`, `data-highlighted`,
 `data-grouped`, `data-depth`, `data-context-menu` and `data-row-id`, so a
 stylesheet can target any of it without a callback. The boolean attributes are
-published on every row as `"true"` or `"false"`, so match the value
-(`[data-grouped="true"]`), not the bare attribute. Pick a `--row-bg` that
+present, with the value `"true"`, only while they apply - `data-grouped` only
+on group rows - so `[data-grouped]` and `[data-grouped="true"]` are
+equivalent. Pick a `--row-bg` that
 reads under both colour schemes - a `-0` Mantine shade is near-white and
 unreadable in dark mode; mix a mid shade into transparency instead.
 

package/skills/server-side/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-side.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-query.md'

package/skills/testing/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.21'
+  library_version: '2.0.0-beta.23'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGrid.tsx'
@@ -33,6 +33,9 @@ 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.
+
 ## Naming a grid
 
 Parts repeat across grids on a page. Name the grid, scope through it:
@@ -58,6 +61,12 @@ accessible name belongs to the element carrying the `grid` role.
 
 Body cells carry no `data-dg-part` - the coordinate pair already names them.
 
+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`,