@jielga/tmdatagrid 1.1.0 → 2.0.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "1.1.0",
+  "version": "2.0.0-beta.0",
   "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

@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.1.0'
+  library_version: '2.0.0-beta.0'
 sources:
   - 'Jielga/TMDataGrid:src/docs/styling.md'
   - 'Jielga/TMDataGrid:src/docs/toolbar.md'

package/skills/cell-selection/SKILL.md

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

package/skills/columns/SKILL.md

@@ -3,19 +3,20 @@ name: columns
 description: >
   Define and arrange TMDataGrid columns. Covers createTMDataGridColumnHelper,
   every column meta field (label, type, options, flex, align, autoSize,
-  enableOrdering, defaultFilterOperator, filterControl, editable, editField,
-  editor, validate), the six column types, fluid minmax sizing versus fixed
-  width with minSize / maxSize / size, autosizing and autosizeColumn, hiding
-  through enableHiding and the columns panel, pinning and why a pinned column
-  becomes fixed-width, ordering with enableColumnOrdering, meta.enableOrdering,
-  moveColumn, moveColumnByStep, getStepTargetColumn and the pinned regions,
-  resetSettings, sorting with multi-sort through isMultiSortEvent and a custom
-  sortFn, and the generated lanes. Load when adding or changing columns,
-  controlling widths, hiding, pinning, reordering or sorting them.
+  enableOrdering, and the meta.filter and meta.edit namespaces holding
+  defaultOperator, control, enabled, field, editor, validate and mapValue), the
+  six column types, fluid minmax sizing versus fixed width with minSize /
+  maxSize / size, autosizing and autosizeColumn, hiding through enableHiding and
+  the columns panel, pinning and why a pinned column becomes fixed-width,
+  ordering with enableColumnOrdering, meta.enableOrdering, moveColumn,
+  moveColumnByStep, getStepTargetColumn and the pinned regions, resetSettings,
+  sorting with multi-sort through isMultiSortEvent and a custom sortFn, and the
+  generated lanes. Load when adding or changing columns, controlling widths,
+  hiding, pinning, reordering or sorting them.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.1.0'
+  library_version: '2.0.0-beta.0'
 sources:
   - 'Jielga/TMDataGrid:src/docs/columns.md'
   - 'Jielga/TMDataGrid:src/docs/column-layout.md'
@@ -65,17 +66,41 @@ column model.
 | `align` | `"left" \| "right" \| "center"` | `"left"` | Applied to both header and cells. |
 | `autoSize` | `boolean` | `false` | Size to the widest mounted content once, after the first rows render. |
 | `enableOrdering` | `boolean` | `true` | `false` keeps the column where it is. |
-| `defaultFilterOperator` | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter on this column starts with. |
-| `filterControl` | `TMDataGridFilterControlComponent` | By `meta.type` | Replaces the value control in this column's filter row. Module scope. |
-| `editable` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. |
-| `editField` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
+| `filter` | `TMDataGridColumnFilterOptions` | – | How this column filters. See below. |
+| `edit` | `TMDataGridColumnEditOptions` | – | How this column is edited. See below. |
+
+What the column **is** stays flat; what a stage **does** with it sits in that
+stage's namespace. `type` and `options` are the shared ground both stages read,
+which is why they are not inside either.
+
+`meta.filter`:
+
+| Field | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `defaultOperator` | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter on this column starts with. |
+| `control` | `TMDataGridFilterControlComponent` | By `meta.type` | Replaces the value control in this column's filter row. Module scope. |
+
+`meta.edit`:
+
+| Field | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `enabled` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. |
+| `field` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
 | `editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Module scope. |
 | `validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
+| `mapValue` | `TMDataGridEditValueMap` | – | Maps each value an editor writes, on every keystroke. |
+
+```tsx
+meta: {
+  type: "number",
+  filter: { defaultOperator: "between", control: DgRangeSliderFilter },
+  edit: { enabled: (row) => !row.original.locked },
+}
+```
 
 `enableOrdering` lives in `meta` because column ordering is the one feature
-TanStack defines no column option for. The four editing fields only act once
-`editMode` is set: see the `editing` skill. `filterControl` and
-`defaultFilterOperator` belong to the `filtering` skill.
+TanStack defines no column option for. `meta.edit` only acts once `editMode` is
+set: see the `editing` skill. `meta.filter` belongs to the `filtering` skill.
 
 ### Column types
 

package/skills/data/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.1.0'
+  library_version: '2.0.0-beta.0'
 sources:
   - 'Jielga/TMDataGrid:src/docs/pagination.md'
   - 'Jielga/TMDataGrid:src/docs/scrolling.md'

package/skills/editing/SKILL.md

@@ -4,19 +4,19 @@ description: >
   Edit cells and rows in TMDataGrid. Covers editMode with its four policies
   (cell, cellConfirm, row, batch), the required getRowId, onEditCommit and
   onEditCommitBatch, why the grid never mutates data, per-column gating with
-  meta.editable and meta.editField, the six built-in editors picked by
-  meta.type, custom editors through meta.editor, field validation with
-  meta.validate and cross-field rules with rowValidators (Standard Schema and
-  Zod), adding and deleting rows with edit.addRow, newRowDefaults, onRowAdd,
-  onRowDelete, the generated edit lane, TMDataGrid.EditActions with its
-  renderActions slot, and the public edit engine (begin, commit, cancel,
-  submitAll, getForm, store). Load when making a grid editable, choosing an edit
-  mode, wiring a save, writing a cell editor, validating an edit, or when cells
-  will not open for editing.
+  meta.edit.enabled and meta.edit.field, the six built-in editors picked by
+  meta.type, custom editors through meta.edit.editor, per-keystroke value
+  mapping with meta.edit.mapValue, field validation with meta.edit.validate and
+  cross-field rules with rowValidators (Standard Schema and Zod), adding and
+  deleting rows with edit.addRow, newRowDefaults, onRowAdd and onRowDelete, the
+  generated edit lane, TMDataGrid.EditActions with its renderActions slot, and
+  the public edit engine (begin, commit, cancel, submitAll, getForm, store).
+  Load when making a grid editable, choosing an edit mode, wiring a save,
+  writing a cell editor, validating an edit, or when cells will not open.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.1.0'
+  library_version: '2.0.0-beta.0'
 sources:
   - 'Jielga/TMDataGrid:src/docs/editing.md'
   - 'Jielga/TMDataGrid:src/docs/query-builder.md'
@@ -90,7 +90,15 @@ An editor opens on double-click, or with the cell cursor on the cell: Enter, F2,
 or just typing, where the character replaces the value. Delete or Backspace
 clears the value and commits without opening an editor. Editing brings cell
 selection with it: `cellSelection` defaults to `"single"` while `editMode` is
-set.
+set. Every open gesture puts the caret in the cell it named, and `edit.addRow()`
+in the new row's first editable cell. The grid places it rather than the editor,
+so a `meta.edit.editor` gets it without doing anything to earn it.
+
+Under `"row"` the pencil - or a double-click on any cell, which puts the caret
+in the cell clicked - opens every editable cell of the row, and ✓ saves them as
+one commit. Rows accumulate: opening a second row leaves the first open, and
+each row's ✓ and ✕ act on that row alone, so no row is closed or saved to make
+space for the next.
 
 Under `"batch"` nothing leaves the grid until `submitAll`. Enter and Tab park
 the draft, dirty-marked, Escape drops that one draft, and drafts accumulate
@@ -114,14 +122,14 @@ the error on the row, which is how a failed save stays visible.
 ## Which cells edit
 
 A column is editable when it maps to a data path: its `accessorKey`, or
-`meta.editField` for a column built on `accessorFn`. Dot paths reach into nested
+`meta.edit.field` for a column built on `accessorFn`. Dot paths reach into nested
 records, so `accessorKey: "address.city"` edits `values.address.city`.
 
 | Gate | Effect |
 | --- | --- |
-| `meta.editable: false` | The column never edits |
-| `meta.editable: (row) => boolean` | Per row, per column |
-| `meta.editField: "lastName"` | The path an `accessorFn` column writes to |
+| `meta.edit.enabled: false` | The column never edits |
+| `meta.edit.enabled: (row) => boolean` | Per row, per column |
+| `meta.edit.field: "lastName"` | The path an `accessorFn` column writes to |
 | `isRowEditable: (row) => boolean` | The whole row, in every mode |
 
 Group rows and the generated lanes (checkbox, row number, details, edit) never
@@ -132,29 +140,23 @@ edit.
 columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
   id: "fullName",
   header: "Full name",
-  meta: { label: "Full name", editField: "lastName" },
+  meta: { label: "Full name", edit: { field: "lastName" } },
 });
 columnHelper.accessor("salary", {
   header: "Salary",
-  meta: { editable: (row) => row.original.status !== "Terminated" },
+  meta: { edit: { enabled: (row) => row.original.status !== "Terminated" } },
 });
 ```
 
 ## Editors and validation
 
-`meta.type` picks the editor, and `meta.options` feeds the select editors from
-the same declaration the filter panel reads.
+`meta.type` picks the editor - `"string"` (the default), `"number"`,
+`"boolean"`, `"date"`, `"select"` and `"multiSelect"` - and `meta.options` feeds
+the two select editors from the same declaration the filter panel reads. Each
+one, with the export that wraps it, is in
+[references/editors-and-validation.md](references/editors-and-validation.md#the-built-in-editors).
 
-| `meta.type` | Editor |
-| --- | --- |
-| `"string"` (default) | Text input |
-| `"number"` | Number input |
-| `"boolean"` | Checkbox |
-| `"date"` | Native `<input type="date">`, ISO `YYYY-MM-DD` |
-| `"select"` | Searchable select from `meta.options`; commits on pick under `"cell"` |
-| `"multiSelect"` | Multi-select, same source |
-
-`meta.editor` replaces one, `meta.validate` guards the field, and
+`meta.edit.editor` replaces one, `meta.edit.validate` guards the field, and
 `rowValidators` carries cross-field rules. The validators are TanStack Form's
 own, Standard Schema included, so a Zod schema passes straight through:
 
@@ -162,7 +164,7 @@ own, Standard Schema included, so a Zod schema passes straight through:
 import { z } from "zod";
 
 // Field level, on the column. A bare schema means { onChange: schema }.
-meta: { validate: z.string().min(2, "At least two characters") }
+meta: { edit: { validate: z.string().min(2, "At least two characters") } }
 
 // Form level, on the hook. Cross-field rules, under "row" or "batch".
 rowValidators: {
@@ -174,11 +176,19 @@ rowValidators: {
 }
 ```
 
-Pathed issues land on the matching cells, pathless ones on the row. Cell corners
-mark state meanwhile: blue for a dirty draft, red for a validation error.
+Pathed issues land on the matching cells, pathless ones on the row, and cell
+corners mark both: blue for a dirty draft, red for a validation error.
+
+`meta.edit.mapValue` rewrites a value rather than rejecting it: uppercase a
+code, strip spaces from an IBAN, clamp a number. It runs on every write an
+editor makes, so a text input maps per keystroke, and what it returns is what
+the validators judge and what commits.
 
-The editor contract, wrapping a built-in, and async server-side field errors:
-[references/editors-and-validation.md](references/editors-and-validation.md).
+```tsx
+meta: { edit: { mapValue: ({ value }) => String(value).toUpperCase() } }
+```
+
+Detail for all three: [references/editors-and-validation.md](references/editors-and-validation.md).
 
 ## Adding and deleting rows
 
@@ -242,17 +252,11 @@ while editing is off, and works under any mode, not only batch.
 
 ## The engine: `edit`
 
-`grid.edit` is public, and everything the chrome does goes through it.
-
-| Member | Does |
-| --- | --- |
-| `edit.begin({ rowId, columnId })` | Opens an editor. `columnId: null` opens the whole row |
-| `edit.commit(rowId)` | Commits one row. `Promise<boolean>`, `false` when blocked |
-| `edit.cancel(rowId)` / `edit.cancelAll()` | Drops one draft, or every draft |
-| `edit.submitAll()` | Commits every open row. `Promise<boolean>` |
-| `edit.addRow()` / `edit.deleteRow(rowId)` | Rows in and out |
-| `edit.getForm(rowId)` | The row's live TanStack Form `FormApi` |
-| `edit.store` | The projection store, for `useSelector` |
+`grid.edit` is public, and everything the chrome does goes through it:
+`begin` and `commit`, `cancel` / `cancelAll`, `submitAll`, `addRow` /
+`deleteRow`, `getForm`, and `store` for `useSelector`. Every member with its
+signature, the gates, `clearCell`, `deactivate`, and the `edit.store` shape are
+in [references/editing-api.md](references/editing-api.md#the-edit-engine).
 
 ```tsx
 import { useSelector } from "@tanstack/react-store";
@@ -263,11 +267,6 @@ const pendingCount = useSelector(
 );
 ```
 
-`edit.store` holds `active`, `openRowIds`, `rows` (per row `dirtyFields`,
-`errorFields`, `isSubmitting`), `newRows` and `deletedRowIds`. The full member
-list, `clearCell`, `deactivate` and the gates included, is in
-[references/editing-api.md](references/editing-api.md).
-
 `getForm` is the *one row, one form* promise made public: render that same form
 in a drawer and it shares values, dirty state and errors with the inline cells,
 because it is the same `FormApi`.
@@ -281,7 +280,7 @@ Use `editMode: "row"` so a row reaches the form on approval, map by row id
 (never index), and mint negative ids for new rows.
 
 The validation split is structural, not stylistic: **a rule decidable from one
-row belongs to the grid (`meta.validate`, `rowValidators`); a rule needing the
+row belongs to the grid (`meta.edit.validate`, `rowValidators`); a rule needing the
 other rows or the collection ("has rows", "no duplicates") belongs to the
 form's field validator.** A row's form cannot see the array, and `edit.store`
 publishes field names, never values, so the form cannot see a draft.
@@ -341,14 +340,14 @@ Source: `src/tmdatagrid/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
 
 ### HIGH A cell editor defined inside the component
 
-`meta.editor` is rendered as JSX, so its identity is its component type. An
+`meta.edit.editor` is rendered as JSX, so its identity is its component type. An
 inline arrow is a new type on every render, which unmounts the open editor and
 loses what was being typed.
 
 Wrong:
 
 ```tsx
-meta: { editor: ({ field }) => <Slider value={field.state.value} /> },
+meta: { edit: { editor: ({ field }) => <Slider value={field.state.value} /> } },
 ```
 
 Correct:
@@ -363,7 +362,7 @@ const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
   />
 );
 
-meta: { editor: SalaryEditor },
+meta: { edit: { editor: SalaryEditor } },
 ```
 
 Source: `src/docs/editors.md`, `src/tmdatagrid/core/editEngine.ts`.
@@ -411,7 +410,7 @@ Correct:
 columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
   id: "fullName",
   header: "Full name",
-  meta: { label: "Full name", editField: "lastName" },
+  meta: { label: "Full name", edit: { field: "lastName" } },
 });
 ```
 
@@ -491,7 +490,8 @@ Source: `src/docs/editing.md` (Adding and deleting rows).
 ## References
 
 - [Editors and validation](references/editors-and-validation.md) - the editor
-  contract, wrapping a built-in, field and row validators, server-side errors.
+  contract, wrapping a built-in, what `mapValue` leaves alone, field and row
+  validators, server-side errors.
 - [Editing API](references/editing-api.md) - every option, callback, column meta
   field, export, CSS variable and data attribute editing owns.
 

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

@@ -35,10 +35,10 @@ path, which may be dotted.
 | --- | --- | --- | --- |
 | `meta.type` | `TMDataGridColumnType` | `"string"` | Picks the built-in editor, and the filter operators. |
 | `meta.options` | `TMDataGridOptionsSource` | – | Choices for `select` / `multiSelect`, shared with the filter panel. Array, `"faceted"`, or a function. |
-| `meta.editable` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. |
-| `meta.editField` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
-| `meta.editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Define at module scope. |
-| `meta.validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
+| `meta.edit.enabled` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. |
+| `meta.edit.field` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
+| `meta.edit.editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Define at module scope. |
+| `meta.edit.validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
 
 ## The `edit` engine
 
@@ -46,7 +46,7 @@ path, which may be dotted.
 
 | Member | Signature | Notes |
 | --- | --- | --- |
-| `begin` | `({ rowId, columnId }) => void` | `columnId: null` opens the whole row (row mode). |
+| `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. |
 | `cancel` | `(rowId) => void` | Drops one draft. |
 | `cancelAll` | `() => void` | Drops every draft. |
@@ -66,7 +66,10 @@ path, which may be dotted.
 
 ```ts
 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.
   openRowIds: ReadonlyArray<string>;
   rows: Record<
     string,

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

@@ -29,7 +29,7 @@ the data), or a function of the table, column and row.
 
 ## The editor contract
 
-`meta.editor` fills the same slot the built-ins fill. It is a **component**,
+`meta.edit.editor` fills the same slot the built-ins fill. It is a **component**,
 rendered as JSX, so hooks are legal inside it.
 
 ```ts
@@ -43,11 +43,16 @@ type TMDataGridEditorArgs = {
   commit: () => Promise<boolean>; // what Enter would do
   cancel: () => void; // what Escape would do
   size: TMDataGridSize;
-  autoFocus: boolean; // take focus on mount
   seedText?: string; // set when typing opened the editor
 };
 ```
 
+The grid places the caret itself, once per open gesture: it focuses
+`data-dg-part="editor-input"` when the editor publishes it, and the first
+focusable element inside the editor otherwise. So a custom editor gets the caret
+without asking for focus - set `editor-input` only to name which of several
+inputs should take it.
+
 Bind any control to `field` exactly as inside any TanStack Form:
 `field.state.value`, `field.state.meta.errors`, `field.handleChange`,
 `field.handleBlur`.
@@ -73,7 +78,7 @@ const SalaryEditor: TMDataGridEditorComponent = ({ field, commit, cancel }) => (
 
 columnHelper.accessor("salary", {
   header: "Salary",
-  meta: { type: "number", editor: SalaryEditor },
+  meta: { type: "number", edit: { editor: SalaryEditor } },
 });
 ```
 
@@ -114,9 +119,52 @@ Pass `args` through whole. `field` is a live TanStack Form `FieldApi`, not a
 plain object, so spreading or rebuilding it loses the binding its methods rely
 on.
 
+## Mapping the value
+
+`meta.edit.mapValue` maps every value an editor writes, before it reaches the
+draft. It runs per write, which for a text input is per keystroke and for a
+select is per pick.
+
+```tsx
+meta: {
+  edit: {
+    // Uppercase as it is typed.
+    mapValue: ({ value }) =>
+      typeof value === "string" ? value.toUpperCase() : value,
+  },
+}
+
+meta: {
+  edit: {
+    // Depends on the record being edited; `previous` is the value the field
+    // held before this write.
+    mapValue: ({ value, previous, row }) =>
+      row.original.country === "SE" ? normalise(value) : previous,
+  },
+}
+```
+
+The grid applies it in the editor host, around the field every editor writes
+through, so it covers the six built-ins, a custom `meta.edit.editor`, and the
+type-to-edit seed character.
+
+Left unmapped on purpose:
+
+- The value an editor opens with. Mapping it would rewrite stored data nobody
+  edited, mark a pristine row dirty and swallow the select-all.
+- `edit.clearCell()`, the Delete key: it writes the type's empty value through
+  the form, so there is no input to map.
+- An editor calling `field.setValue`. `handleChange` is the mapped path.
+
+The built-in string and number editors restore the caret after a mapped write,
+shifted by the length the map changed, because React reassigning `input.value`
+otherwise drops the caret at the end of the field. A custom editor rendering its
+own input has to do the same: record `selectionStart` on change, restore it in a
+layout effect.
+
 ## Field validation
 
-`meta.validate` takes TanStack Form's field-validator vocabulary. A bare schema
+`meta.edit.validate` takes TanStack Form's field-validator vocabulary. A bare schema
 (Zod, or any Standard Schema, or a plain function) means `{ onChange: it }`; the
 object form takes every trigger Form defines.
 
@@ -124,13 +172,13 @@ object form takes every trigger Form defines.
 import { z } from "zod";
 
 // Bare schema: validates on change.
-meta: { validate: z.string().min(2, "At least two characters") }
+meta: { edit: { validate: z.string().min(2, "At least two characters") } }
 
 // Object form: pick the trigger.
-meta: { validate: { onBlur: z.string().email("Not an email address") } }
+meta: { edit: { validate: { onBlur: z.string().email("Not an email address") } } }
 
 // A plain function works too.
-meta: { validate: ({ value }) => (value > 0 ? undefined : "Must be positive") }
+meta: { edit: { validate: ({ value }) => (value > 0 ? undefined : "Must be positive") } }
 ```
 
 `normalizeFieldValidate(validate)` is exported for consumers building their own

package/skills/filtering/SKILL.md

@@ -3,11 +3,11 @@ name: filtering
 description: >
   Narrow the rows a TMDataGrid shows. Covers the shared tmDataGrid filter
   function and its {operator, value} model, the eighteen operators and which
-  meta.type offers each, meta.defaultFilterOperator, isFilterActive and the
+  meta.type offers each, meta.filter.defaultOperator, isFilterActive and the
   half-typed filter, the filter panel, TMDataGrid.FilterButton,
   TMDataGrid.FilterPills with its api prop, openColumnFilter, replacing a value
   control with DgRangeSliderFilter / DgDateRangeFilter / DgAutocompleteFilter /
-  DgTriStateFilter or a meta.filterControl component, per-column filterFn, and
+  DgTriStateFilter or a meta.filter.control component, per-column filterFn, and
   the quick search: TMDataGrid.Search, quickSearchMode fuzzy or contains,
   fuzzyGlobalFilterFn, enableMatchHighlighting and enableGlobalFilter. Load when
   adding filters, choosing operators, building a filter control, showing active
@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.1.0'
+  library_version: '2.0.0-beta.0'
 sources:
   - 'Jielga/TMDataGrid:src/docs/filtering.md'
   - 'Jielga/TMDataGrid:src/docs/quick-search.md'
@@ -70,13 +70,13 @@ and `equals` on a `date` column plays the role of "is". On a `multiSelect`
 column, whose cells hold arrays, `isAnyOf` is an intersection test and `isNoneOf`
 its complement. `between` is inclusive at both ends.
 
-`meta.defaultFilterOperator` sets which one a fresh filter opens on, and must be
+`meta.filter.defaultOperator` sets which one a fresh filter opens on, and must be
 one of the type's own:
 
 ```tsx
 columnHelper.accessor("salary", {
   header: "Salary",
-  meta: { type: "number", defaultFilterOperator: "between" },
+  meta: { type: "number", filter: { defaultOperator: "between" } },
 });
 ```
 
@@ -118,17 +118,16 @@ named exports:
 ```tsx
 meta: {
   type: "number",
-  filterControl: DgRangeSliderFilter,
-  defaultFilterOperator: "between",
+  filter: { control: DgRangeSliderFilter, defaultOperator: "between" },
 }
 ```
 
-Pair the range-shaped ones with `defaultFilterOperator: "between"` so the filter
+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.
 
-`meta.filterControl` is a **component**, rendered as JSX, so hooks are legal
+`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
@@ -157,7 +156,7 @@ const StatusFilter: TMDataGridFilterControlComponent = ({
   </Chip.Group>
 );
 
-meta: { type: "select", filterControl: StatusFilter }
+meta: { type: "select", filter: { control: StatusFilter } }
 ```
 
 `args.options` arrives pre-resolved for a column that declares `meta.options` or
@@ -259,7 +258,7 @@ Source: `src/docs/filtering.md` (Operators).
 
 ### HIGH A filter control defined inside the component
 
-`meta.filterControl` is rendered as JSX, so its identity is its component type.
+`meta.filter.control` is rendered as JSX, so its identity is its component type.
 An inline arrow is a new type every render, which remounts the control and loses
 what was being typed into it.
 
@@ -269,7 +268,7 @@ Correct:
 // Module scope, referenced by name.
 const StatusFilter: TMDataGridFilterControlComponent = (args) => { /* … */ };
 
-meta: { filterControl: StatusFilter }
+meta: { filter: { control: StatusFilter } }
 ```
 
 Source: `src/docs/filtering.md` (Writing your own).
@@ -318,8 +317,8 @@ Source: `src/docs/quick-search.md` (Fuzzy by default).
 | `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the panel, the button and the menu item. |
 | `enableColumnFilter` | Column option | `boolean` | `true` | `false` takes one column out of filtering. |
 | `meta.type` | Column meta | `TMDataGridColumnType` | `"string"` | Selects the operators and the value control. |
-| `meta.defaultFilterOperator` | Column meta | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter opens on. |
-| `meta.filterControl` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. Module scope. |
+| `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter opens on. |
+| `meta.filter.control` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. Module scope. |
 | `filterFn` | Column option | name or fn | `"tmDataGrid"` | Custom matching for one column. |
 | `quickSearchMode` | Option | `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
 | `enableMatchHighlighting` | Option | `boolean` | `false` | Mark matched text in default-rendered cells. |

package/skills/getting-started/SKILL.md

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

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.1.0'
+  library_version: '2.0.0-beta.0'
 sources:
   - 'Jielga/TMDataGrid:src/docs/grouping.md'
   - 'Jielga/TMDataGrid:src/docs/summary-row.md'

package/skills/options/SKILL.md

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

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.1.0'
+  library_version: '2.0.0-beta.0'
 sources:
   - 'Jielga/TMDataGrid:src/docs/row-selection.md'
   - 'Jielga/TMDataGrid:src/docs/row-interaction.md'
@@ -249,10 +249,15 @@ const grid = useTMDataGrid({
 });
 ```
 
-There is no built-in pin gesture - pin from wherever suits, most naturally the
-row context menu, through TanStack's own `row.pin("top" | "bottom" | false)`,
-`row.getIsPinned()` and `row.getCanPin()`. Pinned rows leave the scrolling order
-and render in sticky blocks: top under the header, bottom above the summary row.
+There is no built-in pin gesture and no pin icon - build one from TanStack's own
+`row.pin("top" | "bottom" | false)`, `row.getIsPinned()` and `row.getCanPin()`,
+either as a display column whose cell is a pin button or in the row context
+menu. Read the pinned state through a subscription
+(`useSelector(row.table.store, () => row.getIsPinned())`) rather than calling it
+in a component body: the `row` identity survives a pin, so the React Compiler
+would cache the call and the icon would never change. Whichever gesture you
+build, put unpin in it too. Pinned rows leave the scrolling order and render in
+sticky blocks: top under the header, bottom above the summary row.
 
 Pinned rows are still body rows - selection, editing, details, the context menu
 and per-row styling all behave normally. What they sit out are the statements