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

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

@@ -0,0 +1,177 @@
+# Editing - common mistakes
+
+The failure modes that compile, raise no warning, and lose a user's typing.
+Severity is how much data or trust the mistake costs.
+
+## CRITICAL Expecting the grid to write into `data`
+
+The grid holds no copy of the rows. Without `editing.onCommit` an edit commits,
+the draft clears, and the cell reverts to the value in `data`.
+
+Wrong:
+
+```tsx
+useTMDataGrid({
+  data: employees,
+  columns,
+  getRowId,
+  editing: { mode: "cell" },
+});
+```
+
+Correct: wire `editing.onCommit` to apply the change where the data lives, as
+in the skill's Setup section.
+
+Source: `src/docs/editing.md`, `src/tmdatagrid/core/editEngine.ts`.
+
+## CRITICAL `getRowId` built from the row index
+
+`getRowId` accepts any string, so an index-based id compiles. Drafts are keyed
+by it, so after a sort or a filter the draft is applied to whichever record now
+sits at that index.
+
+Wrong:
+
+```tsx
+getRowId: (row, index) => String(index),
+```
+
+Correct:
+
+```tsx
+getRowId: (row) => String(row.id),
+```
+
+Source: `src/tmdatagrid/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
+
+## HIGH A cell editor defined inside the component
+
+`meta.edit.editor` is rendered as JSX, so its identity is its component type. An
+inline arrow function is a new type on every render, which unmounts the open
+editor and discards what was being typed.
+
+Wrong:
+
+```tsx
+meta: { edit: { editor: ({ field }) => <Slider value={field.state.value} /> } },
+```
+
+Correct:
+
+```tsx
+// Module scope, referenced by name.
+const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
+  <Slider
+    value={Number(field.state.value ?? 0)}
+    onChange={(next) => field.handleChange(next)}
+    onChangeEnd={() => void commit()}
+  />
+);
+
+meta: { edit: { editor: SalaryEditor } },
+```
+
+Source: `src/docs/editors.md`, `src/tmdatagrid/core/editEngine.ts`.
+
+## HIGH A cross-field rule under `editing.mode: "cell"`
+
+Under `"cell"` each cell commits on its own, so a rule spanning two columns
+cannot be satisfied by either one: the first cell edited is rejected against the
+other column's old value, and the row cannot be saved.
+
+Correct: `editing.rowValidators` needs `mode: "row"` or `"draft"`, which
+validate the whole row in one commit.
+
+Source: `src/docs/editors.md` (Validation).
+
+## HIGH An `accessorFn` column that never opens an editor
+
+Editability follows the data path, not the column. A column built on an accessor
+function has no `accessorKey`, so it maps to nothing and stays read-only while
+every other column edits. No warning is raised.
+
+Wrong:
+
+```tsx
+columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
+  id: "fullName",
+  header: "Full name",
+});
+```
+
+Correct:
+
+```tsx
+columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
+  id: "fullName",
+  header: "Full name",
+  meta: { label: "Full name", edit: { field: "lastName" } },
+});
+```
+
+Source: `src/docs/editing.md` (Which cells edit).
+
+## HIGH Swallowing the error in `editing.onCommit`
+
+The draft is dropped when `editing.onCommit` resolves. A `try/catch` that logs
+the failure resolves it, so a save that failed on the server clears the editor
+and the grid shows the old value as though nothing happened.
+
+Wrong:
+
+```tsx
+onCommit: async ({ rowId, changes }) => {
+  try {
+    await api.patch(rowId, changes);
+  } catch (error) {
+    console.error(error);
+  }
+},
+```
+
+Correct: no `catch` - let the rejection propagate, and the form stays open
+with the error on the row.
+
+Source: `src/tmdatagrid/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
+
+## HIGH Submitting an outer form while the grid holds a draft
+
+The outer form's array contains only committed rows. Under any mode a mid-edit
+row is invisible to it, and under `"draft"` every edit is until `submitAll()`,
+so a form submit saves stale rows and collection rules skip pending values.
+
+Correct:
+
+```tsx
+const hasOpenDraft = useSelector(grid.edit.store, (s) => s.openRowIds.length > 0);
+
+<Button type="submit" disabled={!canSubmit || hasOpenDraft}>Save</Button>
+// or flush instead of blocking:
+const flushed = await grid.edit.submitAll();
+if (flushed) await form.handleSubmit();
+```
+
+Source: `src/docs/query-builder.md` (Which mode, Submitting).
+
+## MEDIUM Reading a commit's result as the saved value
+
+`edit.commit(rowId)` and `edit.submitAll()` resolve to a `boolean` saying
+whether the form closed, and resolve `false` when validation or a rejected save
+kept it open. Ignoring the result reports a save that did not happen.
+
+```tsx
+const saved = await grid.edit.submitAll();
+notifications.show({ message: saved ? "Saved" : "Some rows need attention" });
+```
+
+Source: `src/tmdatagrid/core/editEngine.ts` (`TMDataGridEditApi`).
+
+## MEDIUM Expecting `editing.onRowDelete` to fire under draft
+
+Under the immediate modes `edit.deleteRow` calls `editing.onRowDelete` at once.
+Under `"draft"` it only toggles a deletion mark, so nothing is removed until
+`submitAll`: the ids arrive as `deleted` in `editing.onCommitDrafts`, or, with
+no such callback, in the per-row `editing.onRowDelete` loop. A confirmation
+placed inside `editing.onRowDelete` therefore guards the save, not the trash.
+
+Source: `src/docs/editing.md` (Adding and deleting rows).

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

@@ -7,24 +7,27 @@ kind.
 
 | Name | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `editMode` | `"cell" \| "cellConfirm" \| "row" \| "batch"` | off | Turns editing on and picks the commit policy. |
-| `getRowId` | `(row) => string` | – | A TanStack table option, required once `editMode` is set. Drafts are keyed by it. |
-| `isRowEditable` | `(row) => boolean` | – | Closes a whole row to editing, in every mode. |
-| `rowValidators` | `TMDataGridRowValidators` | – | Form-level validation. Cross-field rules live here. |
-| `newRowDefaults` | `TData \| (() => TData)` | – | Seeds the entry row's form. A function is called per added row. |
-| `cellSelection` | `"none" \| "single" \| "range"` | `"single"` while editing | Editing turns the cell cursor on; set it explicitly to override. |
-
-Passing any editing option without `editMode` is a compile error, and
-`onEditCommitBatch` exists only in the `"batch"` branch of the type.
+| `editing` | `TMDataGridEditingOptions` | off | The editing namespace. Setting it turns editing on. |
+| `editing.mode` | `"cell" \| "cellConfirm" \| "row" \| "draft"` | – | Picks the commit policy. |
+| `getRowId` | `(row) => string` | – | A TanStack table option, required once `editing` is set. Drafts are keyed by it. |
+| `editing.isRowEditable` | `(row) => boolean` | – | Closes a whole row to editing, in every mode. |
+| `editing.rowValidators` | `TMDataGridRowValidators` | – | Form-level validation. Cross-field rules live here. |
+| `editing.newRowDefaults` | `TData \| (() => TData)` | – | Seeds the entry row's form. A function is called per added row. |
+| `editing.newRowsSticky` | `boolean` | `false` | Draft mode only. Keeps entered new rows pinned in the entry block until Save all, instead of letting them scroll with the body. |
+| `cellSelection` | `"none" \| "single" \| "range"` | `"single"` while `editing` is set | Editing turns the cell cursor on; set it explicitly to override. |
+
+Passing any other member of `editing` without `mode` is a compile error, and
+`onCommitDrafts` and `newRowsSticky` exist only in the `"draft"` branch of the
+type.
 
 ## Callbacks
 
 | Name | Argument | What it does |
 | --- | --- | --- |
-| `onEditCommit` | `{ rowId, value, original, changes, source }` | Applies one row's change. Reject to keep the draft and show the error. |
-| `onEditCommitBatch` | `{ rows, added, deleted }` | Batch only. One call for the whole save. Without it, `submitAll` loops `onEditCommit`. |
-| `onRowAdd` | `{ tempId, value }` | Commits an entry row. Mint the real id here. |
-| `onRowDelete` | `{ rowId, row }` | Deletes a row under the immediate modes, and puts the trash can in the edit lane. |
+| `editing.onCommit` | `{ rowId, value, original, changes, source }` | Applies one row's change. Reject to keep the draft and show the error. |
+| `editing.onCommitDrafts` | `{ rows, added, deleted }` | Draft mode only. One call for the entire save. Without it, `submitAll` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
+| `editing.onRowAdd` | `{ tempId, value }` | Commits an entry row. Mint the real id here. |
+| `editing.onRowDelete` | `{ rowId, row }` | Deletes a row under the immediate modes, and puts the trash can in the edit lane. |
 
 `changes` entries are `{ columnId, field, previous, next }`; `field` is the data
 path, which may be dotted.
@@ -46,18 +49,18 @@ path, which may be dotted.
 
 | Member | Signature | Notes |
 | --- | --- | --- |
-| `begin` | `({ rowId, columnId }) => void` | Row mode opens the whole row either way; `columnId` says which cell takes the caret, `null` (the pencil) its first editable one. |
-| `commit` | `(rowId) => Promise<boolean>` | `false` keeps the form open with its errors. |
+| `begin` | `({ rowId, columnId }) => void` | Row mode opens the entire row either way. `columnId` selects which cell takes the caret; `null` (the pencil) uses its first editable one. On an entered new row it reopens the row, flipping `confirmed` back to `false`. |
+| `commit` | `(rowId) => Promise<boolean>` | `false` keeps the form open with its errors. Under `"draft"` it validates and holds the draft: no consumer callback runs until `submitAll`. |
 | `cancel` | `(rowId) => void` | Drops one draft. |
 | `cancelAll` | `() => void` | Drops every draft. |
 | `deactivate` | `() => void` | Closes the editor without touching the draft, as blur does under `"cellConfirm"`. |
-| `submitAll` | `() => Promise<boolean>` | Batch's save. `true` when every row landed. |
+| `submitAll` | `() => Promise<boolean>` | Draft mode's Save all. `true` when every row landed. |
 | `clearCell` | `(rowId, columnId) => Promise<boolean>` | What Delete does: writes the type's empty value and commits. |
 | `addRow` | `() => string` | Opens an entry row, returns its `tempId`. |
-| `deleteRow` | `(rowId) => void` | `onRowDelete` under the immediate modes, a deletion mark under batch. |
-| `canEditCell` | `(row, column) => boolean` | The gate the chrome uses. |
+| `deleteRow` | `(rowId) => void` | `editing.onRowDelete` under the immediate modes, a deletion mark under draft mode. Toggles: a second call restores the row. |
+| `canEditCell` | `(row, column) => boolean` | The check the built-in controls use. |
 | `canEditRow` | `(row) => boolean` | The pencil's gate. |
-| `canDeleteRows` | `() => boolean` | Whether delete chrome makes sense. |
+| `canDeleteRows` | `() => boolean` | Whether the delete control should be shown. |
 | `getForm` | `(rowId) => TMDataGridRowEditForm \| undefined` | The row's live `FormApi`. |
 | `state` | `TMDataGridEditState` | Snapshot, for reads outside React. |
 | `store` | `Store<TMDataGridEditState>` | For `useSelector`. |
@@ -69,17 +72,23 @@ type TMDataGridEditState = {
   // The cell the last open gesture named - where the caret goes.
   active: { rowId: string; columnId: string | null } | null;
   // Rows with a live form. One under `"cell"`; as many as the user opened
-  // under `"row"`, `"cellConfirm"` and `"batch"` - which rows are editing.
+  // under `"row"`, `"cellConfirm"` and `"draft"` - which rows are editing.
   openRowIds: ReadonlyArray<string>;
+  // One `TMDataGridEditRowProjection` per open row.
   rows: Record<
     string,
     {
       dirtyFields: ReadonlyArray<string>;
       errorFields: ReadonlyArray<string>;
+      hasRowError: boolean;
       isSubmitting: boolean;
+      // The row as drafted, reference-stable while no value changes.
+      values: TMDataGridRowData;
     }
   >;
-  newRows: ReadonlyArray<{ tempId: string }>;
+  // `confirmed` is draft mode's "entered, awaiting Save all". Under the
+  // immediate modes a confirm commits through `onRowAdd`, so it stays `false`.
+  newRows: ReadonlyArray<{ tempId: string; confirmed: boolean }>;
   deletedRowIds: ReadonlyArray<string>;
 };
 ```
@@ -97,7 +106,7 @@ type TMDataGridEditState = {
 | `TMDataGridStringEditor` … `TMDataGridMultiSelectEditor` | Exports | The six built-in editors, for wrapping. |
 
 Types: `TMDataGridEditMode`, `TMDataGridEditApi`, `TMDataGridEditState`,
-`TMDataGridEditCommitArgs`, `TMDataGridEditCommitBatchArgs`,
+`TMDataGridEditCommitArgs`, `TMDataGridEditCommitDraftsArgs`,
 `TMDataGridEditChange`, `TMDataGridEditorArgs`, `TMDataGridEditorComponent`,
 `TMDataGridEditField`, `TMDataGridEditRowProjection`, `TMDataGridFieldValidate`,
 `TMDataGridRowValidators`, `TMDataGridRowEditForm`, `TMDataGridRowAddArgs`,
@@ -108,20 +117,39 @@ Types: `TMDataGridEditMode`, `TMDataGridEditApi`, `TMDataGridEditState`,
 Generated, pinned right, id `EDIT_COLUMN_ID`. It appears when any of these
 holds:
 
-- `editMode: "row"` - the lane is Save and Cancel's home
-- `onRowDelete` is set - the trash can has somewhere to report to
-- `editMode: "batch"` **and** `onEditCommitBatch` is set
+- `editing.mode: "row"` - the lane is Save and Cancel's home
+- `editing.mode: "draft"` - the lane is the change indicator and the per-row
+  revert, and `editing.onCommitDrafts` is not required for it
+- `editing.onRowDelete` is set - the trash can has somewhere to report to
+
+`"cell"` and `"cellConfirm"` have no lane unless `editing.onRowDelete` asks for
+one.
 
-`"cell"` and `"cellConfirm"` have no lane unless `onRowDelete` asks for one.
+What the lane holds depends on the mode. Under `"row"` an open row shows
+`save-row` and `cancel-row`; those two never render under `"draft"`. Under
+`"draft"` every changed row shows `row-state`, whose `data-state` is `new`,
+`edited` or `deleted`, together with `revert-row` on an edited row,
+`restore-row` on one marked for deletion, and `edit-row` plus `discard-new-row`
+on an entered new row. A row holding a dirty draft hides `delete-row`. Every
+control carries a tooltip from the labels, `revertRow`, `rowStateNew`,
+`rowStateEdited` and `rowStateDeleted` among them.
 
 ## Styling and test hooks
 
 | Name | Kind | What it is |
 | --- | --- | --- |
 | `--dg-entry-height` | CSS variable | Height of the sticky entry block. From `size`. |
-| `data-deleted` | Row attribute | On a row marked for deletion under batch. |
+| `--dg-row-new-bg` | CSS variable | Background of an entered new row. A green tint. |
+| `data-deleted` | Row attribute | On a row marked for deletion under draft mode. |
+| `data-dirty` | Row attribute | On a body row holding a dirty draft. Also on the cell whose field is dirty. |
+| `data-new` / `data-confirmed` | Entry row attributes | On an entry row; `data-confirmed` once it is entered, awaiting Save all. |
+| `data-dg-entry-flow-block` | Attribute | The in-flow block above the body rows holding entered new rows, unless `editing.newRowsSticky` keeps them in the sticky entry block. |
 | `data-dg-part="editor-input"` | Part | The control inside an editing cell. |
-| `data-dg-part="save-row"` / `"cancel-row"` | Parts | The edit lane's buttons, with `data-row-id`. |
+| `data-dg-part="save-row"` / `"cancel-row"` | Parts | The edit lane's buttons on an open row, with `data-row-id`. Row mode only. |
+| `data-dg-part="row-state"` | Part | Draft mode's change marker, with `data-row-id` and `data-state` of `new`, `edited` or `deleted`. |
+| `data-dg-part="revert-row"` / `"restore-row"` | Parts | Drops a row's draft, and undoes a deletion mark, with `data-row-id`. |
+| `data-dg-part="edit-row"` / `"delete-row"` | Parts | The idle lane's pencil and trash, with `data-row-id`. `edit-row` also reopens an entered new row. |
+| `data-dg-part="confirm-new-row"` / `"discard-new-row"` | Parts | An entry row's ✓ and ✕, with `data-row-id`. |
 | `data-dg-part="save-all"` / `"discard-all"` | Parts | `EditActions`. |
 
 See the `testing` skill for how to compose these into selectors.

package/skills/editing/references/editors-and-validation.md

@@ -27,15 +27,15 @@ columnHelper.accessor("department", {
 `meta.options` takes a static array, `"faceted"` (the distinct values present in
 the data), or a function of the table, column and row.
 
-## The editor contract
+## The editor API
 
-`meta.edit.editor` fills the same slot the built-ins fill. It is a **component**,
-rendered as JSX, so hooks are legal inside it.
+`meta.edit.editor` fills the same slot as the built-ins. It is a **component**,
+rendered as JSX, so hooks may be used inside it.
 
 ```ts
 type TMDataGridEditorArgs = {
   field: TMDataGridEditField; // the live TanStack Form field
-  form: TMDataGridRowEditForm; // the whole row's form, for sibling fields
+  form: TMDataGridRowEditForm; // the row's form, for sibling fields
   cell: Cell;
   row: Row;
   column: Column;
@@ -85,7 +85,8 @@ columnHelper.accessor("salary", {
 ## Wrapping a built-in
 
 The built-ins take `TMDataGridEditorArgs` as their props, so a custom editor can
-pass the whole object through and add around it rather than start over.
+pass the whole object through and render around it instead of starting from
+scratch.
 
 ```tsx
 import { Group, Text } from "@mantine/core";
@@ -186,22 +187,24 @@ column factories: it turns a bare schema into Form's validator shape.
 
 ## Row validation
 
-`rowValidators` is form-level, and where cross-field rules live.
+`editing.rowValidators` is form-level, and where cross-field rules live.
 
 ```tsx
 const grid = useTMDataGrid({
   data: employees,
   columns,
   getRowId: (row) => String(row.id),
-  editMode: "row",
-  rowValidators: {
-    onSubmit: z
-      .object({ salary: z.number().positive(), status: z.string() })
-      .refine((row) => row.status !== "Terminated" || row.salary === 0, {
-        message: "A terminated employee has no salary",
-      }),
+  editing: {
+    mode: "row",
+    rowValidators: {
+      onSubmit: z
+        .object({ salary: z.number().positive(), status: z.string() })
+        .refine((row) => row.status !== "Terminated" || row.salary === 0, {
+          message: "A terminated employee has no salary",
+        }),
+    },
+    onCommit,
   },
-  onEditCommit,
 });
 ```
 
@@ -211,12 +214,12 @@ issue lands on the column whose `editField` is `"address.city"`.
 
 Cross-field rules need a mode that commits the whole row at once. Under `"cell"`
 each cell commits alone, so the rule is evaluated against the other column's
-unedited value and can never pass. Use `"row"` or `"batch"`.
+unedited value and cannot pass. Use `"row"` or `"draft"`.
 
 ## Server-side errors
 
-`rowValidators.onSubmitAsync` returns TanStack Form's `{ form, fields }` shape,
-so an API's field errors land on the right cells without translation.
+`editing.rowValidators.onSubmitAsync` returns TanStack Form's `{ form, fields }`
+shape, so an API's field errors land on the right cells without translation.
 
 ```tsx
 rowValidators: {
@@ -232,15 +235,19 @@ rowValidators: {
 ```
 
 A commit blocked by validation keeps the editor open with the message on the
-input. A rejected `onEditCommit` keeps the draft too, with the error on the row.
+input. A rejected `editing.onCommit` keeps the draft too, with the error on the
+row.
 
 ## Where the state shows
 
 | Marker | Means |
 | --- | --- |
+| The cell's own value | A held draft is displayed: the cell renders the draft value through the column's `cell` renderer, in every mode |
 | Blue cell corner | The field is dirty against its original value |
 | Red cell corner | The field carries a validation error |
 | Row error text | A pathless rule failed, or a commit was rejected |
+| `data-dirty` on the row | The row holds a dirty draft |
 
 The same information is readable from `edit.store`: `rows[rowId].dirtyFields`,
-`rows[rowId].errorFields`, `rows[rowId].isSubmitting`.
+`rows[rowId].errorFields`, `rows[rowId].hasRowError`,
+`rows[rowId].isSubmitting`, and `rows[rowId].values` for the draft itself.

package/skills/filtering/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.0'
+  library_version: '2.0.0-beta.2'
 sources:
   - 'Jielga/TMDataGrid:src/docs/filtering.md'
   - 'Jielga/TMDataGrid:src/docs/quick-search.md'
@@ -46,10 +46,10 @@ The model is therefore plain JSON: dates as ISO `YYYY-MM-DD`, booleans as
 cell is tested against) and `between` (a `[min, max]` pair, an empty string
 leaving that end open).
 
-A filter with an empty value **stays in state** so the panel keeps showing its
-row while the reader types. It matches every row, does not light the header
-indicator and gets no pill. `isFilterActive(value)` is the test for that state -
-presence in `columnFilters` is not.
+A filter with an empty value **stays in state** so the panel keeps its row while
+the user types. It matches every row, does not set the header indicator and
+produces no pill. `isFilterActive(value)` tests for that state; presence in
+`columnFilters` does not.
 
 ## Operators
 
@@ -66,12 +66,12 @@ presence in `columnFilters` is not.
 Every type also offers `isEmpty` and `isNotEmpty`, which ignore the value input.
 
 String comparisons are case-insensitive. Date comparisons are by calendar day,
-and `equals` on a `date` column plays the role of "is". On a `multiSelect`
+so `equals` on a `date` column matches the same day. On a `multiSelect`
 column, whose cells hold arrays, `isAnyOf` is an intersection test and `isNoneOf`
 its complement. `between` is inclusive at both ends.
 
 `meta.filter.defaultOperator` sets which one a fresh filter opens on, and must be
-one of the type's own:
+one of the operators that type offers:
 
 ```tsx
 columnHelper.accessor("salary", {
@@ -85,10 +85,10 @@ columnHelper.accessor("salary", {
 `TMDataGrid.FilterPanel` is column, operator and value rows under a "Filters"
 header, above "Add filter" and "Clear all". It is rendered by
 `TMDataGrid.Table`; Escape and a click outside close it, with `FilterButton`
-exempt from the click-away so it stays a toggle. Closing only hides it - the
+exempt from the click-away so it stays a toggle. Closing only hides it; the
 filters stay. **Clear all** drops every filter, half-typed ones included.
 
-`TMDataGrid.FilterPills` takes the grid as an `api` prop rather than reading
+`TMDataGrid.FilterPills` takes the grid as an `api` prop instead of reading
 context, so active filters can live in a page header or anywhere else:
 
 ```tsx
@@ -97,7 +97,7 @@ import { TMDataGridFilterPills } from "@jielga/tmdatagrid";
 <TMDataGridFilterPills api={grid} onPillClick={(columnId) => focus(columnId)} />;
 ```
 
-One pill per **active** filter - `First name: Sofia ✕` - where ✕ clears it and a
+One pill per **active** filter, `First name: Sofia ✕`, where ✕ clears it and a
 click on the label reopens the panel on its column. The label spells the
 operator out unless it is the type's default: `Age is greater than 30`, but
 `First name: Sofia`. `openColumnFilter(api, columnId)` does the same reopening
@@ -123,15 +123,15 @@ meta: {
 ```
 
 Pair the range-shaped ones with `defaultOperator: "between"` so the filter
-opens on them. For operators outside their shape every built-in falls back to
-`TMDataGridFilterValueInput`, which is exported so a custom control can take the
-same escape.
+opens on them. For an operator they do not cover, every built-in falls back to
+`TMDataGridFilterValueInput`, which is exported so custom controls can fall back
+the same way.
 
-`meta.filter.control` is a **component**, rendered as JSX, so hooks are legal
-inside. It is a **value-only contract**: it reads `operator` to shape itself and
-writes the bare value through `onChange`, and the grid composes the stored
-`{ operator, value }` around it. The column and operator dropdowns stay the
-panel's.
+`meta.filter.control` is a **component**, rendered as JSX, so hooks may be used
+inside. It handles the value only: it reads `operator` to shape itself and
+writes the bare value through `onChange`, and the grid stores the
+`{ operator, value }` pair around it. The column and operator dropdowns remain
+the panel's.
 
 ```tsx
 import type { TMDataGridFilterControlComponent } from "@jielga/tmdatagrid";
@@ -160,16 +160,17 @@ meta: { type: "select", filter: { control: StatusFilter } }
 ```
 
 `args.options` arrives pre-resolved for a column that declares `meta.options` or
-is select-shaped; `args.table` is the escape hatch for a control that must reach
-further.
+is select-shaped. `args.table` is available to a control that needs more than
+that.
 
-To give a column its own *matching* rather than its own control, set `filterFn`
-on the column definition. The grid only provides `"tmDataGrid"` as the default.
+To give a column its own *matching* instead of its own control, set `filterFn`
+on the column definition. The grid provides only `"tmDataGrid"`, which is the
+default.
 
 ## Quick search
 
-`TMDataGrid.Search` is a debounced input writing TanStack's `globalFilter`. No
-option turns it on: you render it or you do not.
+`TMDataGrid.Search` is a debounced input writing TanStack's `globalFilter`.
+There is no option to turn it on: render the component, or do not.
 
 ```tsx
 <TMDataGrid.Toolbar>
@@ -177,37 +178,37 @@ option turns it on: you render it or you do not.
 </TMDataGrid.Toolbar>
 ```
 
-Matching is **fuzzy by default**: typos and skipped characters are forgiven, and
+Matching is **fuzzy by default**: typos and skipped characters still match, and
 while the search is the only thing narrowing the grid (no sort, no grouping) the
-rows order by match quality, best first. That ordering is derived, never written
-into `sorting` - no column claims `aria-sort`, nothing lands in the persisted
-slices, and the reader's next sort click takes over just by existing.
+rows are ordered by match quality, best first. That ordering is derived and
+never written into `sorting`: no column takes `aria-sort`, nothing is written to
+the persisted slices, and the next sort click replaces it.
 
 `quickSearchMode: "contains"` restores plain substring matching. An explicit
 `globalFilterFn` overrides both, and switches the rank ordering off with it.
 `fuzzyGlobalFilterFn` is exported for a custom input over the same matching.
 
-`enableMatchHighlighting: true` marks the matched slice of a cell's text, under
+`enableMatchHighlighting: true` marks the matched part of a cell's text, under
 the quick search or a `contains` / `startsWith` / `endsWith` column filter. What
-gets marked is the contiguous, case-insensitive occurrence, so a fuzzy
-typo-match with no contiguous occurrence shows no highlight. It applies to
-**default-rendered cells only**: a column with its own `cell` renderer opts out
-by existing.
+is marked is the contiguous, case-insensitive occurrence, so a fuzzy typo-match
+with no contiguous occurrence is not highlighted. It applies to
+**default-rendered cells only**: a column with its own `cell` renderer is
+excluded.
 
 ## Turning it off
 
 `enableColumnFilters: false` removes the panel, the button and the menu item;
 `enableColumnFilter: false` on a column takes that column out.
 `enableGlobalFilter: false` removes the search input, or on a column removes its
-participation in the search. Generated lanes already opt out.
+participation in the search. The generated lanes are already excluded.
 
 ## Common mistakes
 
 ### CRITICAL Treating presence in `columnFilters` as an active filter
 
-A half-typed filter stays in state on purpose, so the panel keeps its row while
-the reader types. Counting entries reports filters that are narrowing nothing,
-and forwarding them to a server sends `{ operator: "contains", value: "" }` as a
+A half-typed filter stays in state deliberately, so the panel keeps its row
+while the user types. Counting entries reports filters that narrow nothing, and
+forwarding them to a server sends `{ operator: "contains", value: "" }` as a
 real constraint.
 
 Wrong:
@@ -251,8 +252,8 @@ Source: `src/tmdatagrid/core/filterOperators.ts`.
 
 `getColumnType` defaults to `"string"`, so a numeric column that omits
 `meta: { type: "number" }` offers only the string operators. `greaterThan` and
-`between` never appear in the panel, and comparisons run as text - `"9"` sorts
-above `"10"`.
+`between` never appear in the panel, and comparisons run as text, where `"9"`
+sorts above `"10"`.
 
 Source: `src/docs/filtering.md` (Operators).
 
@@ -275,9 +276,9 @@ Source: `src/docs/filtering.md` (Writing your own).
 
 ### MEDIUM Writing the whole filter from a custom control
 
-The contract is value-only: `onChange` takes the bare value, and the grid
-composes `{ operator, value }` around it. Passing an object writes a filter
-whose `value` is itself an object, which no operator can match against.
+A control handles the value only: `onChange` takes the bare value, and the grid
+stores `{ operator, value }` around it. Passing an object writes a filter whose
+`value` is itself an object, which no operator can match against.
 
 Wrong:
 
@@ -295,18 +296,18 @@ Source: `src/docs/filtering.md` (Writing your own).
 
 ### MEDIUM Expecting match highlighting in a custom cell
 
-The grid replicates the default value-to-string render with marks added, and
-never rummages inside a custom renderer's output. A column with a `cell`
-renderer shows no marks however `enableMatchHighlighting` is set. Equality
-operators highlight nothing either.
+The grid reproduces the default value-to-string render with marks added, and
+does not modify a custom renderer's output. A column with a `cell` renderer
+shows no marks whatever `enableMatchHighlighting` is set to. Equality operators
+highlight nothing either.
 
 Source: `src/docs/quick-search.md` (Match highlighting).
 
 ### MEDIUM Expecting fuzzy ranking to survive a sort
 
 The rank ordering applies only while the search is the sole narrowing. Any sort
-or grouping takes over, by design - the ordering is derived and never written
-into `sorting`, so there is nothing to clear afterwards.
+or grouping replaces it. The ordering is derived and never written into
+`sorting`, so there is nothing to clear afterwards.
 
 Source: `src/docs/quick-search.md` (Fuzzy by default).
 
@@ -329,11 +330,11 @@ Source: `src/docs/quick-search.md` (Fuzzy by default).
 | `TMDataGrid.FilterPills` | Component | `api`, `size`, `showClearAll`, `onPillClick`, `className` | – | Active filters as removable pills, renderable anywhere. |
 | `TMDataGrid.Search` | Component | `placeholder`, `debounce` (`250`), `w` (`220`) | – | The debounced quick-search input. |
 | `openColumnFilter` | Export | `(api, columnId) => void` | – | Opens the panel on a column. |
-| `isFilterActive` | Export | `(value) => boolean` | – | Whether a filter value is doing anything. |
+| `isFilterActive` | Export | `(value) => boolean` | – | Whether a filter value narrows anything. |
 | `getOperatorsForType` | Export | `(type) => operators` | – | The operator list a type offers. |
 | `FILTER_OPERATOR_LABELS` | Export | record | – | The label shown for each operator. |
 | `formatFilterLabel` | Export | `({ label, type, filter }) => string` | – | The one-line description used on the pills. |
-| `emptyValueForOperator` · `operatorNeedsValue` · `operatorTakesArrayValue` · `operatorTakesRangeValue` | Exports | – | – | What shape of value an operator wants. |
+| `emptyValueForOperator` · `operatorNeedsValue` · `operatorTakesArrayValue` · `operatorTakesRangeValue` | Exports | – | – | What shape of value an operator expects. |
 | `TMDataGridFilterValueInput` | Export | component | – | The default value control, for falling back to. |
 | `DgRangeSliderFilter` · `DgDateRangeFilter` · `DgAutocompleteFilter` · `DgTriStateFilter` | Exports | components | – | The four ready-made controls. |
 | `fuzzyGlobalFilterFn` | Export | filter fn | – | The default matcher, for a custom input. |