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

package/README.md

@@ -1,9 +1,9 @@
 # TMDataGrid
 
-A data grid for React built on [TanStack Table v9](https://tanstack.com/table) and
-[Mantine](https://mantine.dev). Rows are always virtualized, columns are resizable,
-reorderable, sortable, filterable, hideable and pinnable, and every piece of grid
-chrome is a component you opt into.
+A data grid for React built on [TanStack Table v9](https://tanstack.com/table)
+and [Mantine](https://mantine.dev). Rows are always virtualized, columns are
+resizable, reorderable, sortable, filterable, hideable and pinnable, and every
+part of the grid interface is a component you render yourself.
 
 ## Installation
 
@@ -79,18 +79,16 @@ export function Employees({ data }: { data: Employee[] }) {
 ```
 
 Only the parts you render exist, and only the features you enable have state.
-Pagination is opt-in via `enablePagination` (implied by `manualPagination`) -
-by default every row renders, virtualized. A column that defines no filter
-shows no filter control.
+Pagination is opt in through `enablePagination` (implied by `manualPagination`);
+by default every row renders, virtualized. A column that defines no filter shows
+no filter control.
 
 ## Documentation
 
-The documentation is written as markdown under [`src/docs/`](src/docs) and served by the
-demo site:
-
-One page per touchpoint: the prose, the demos that show it, and the reference
-table for everything that page owns. [`docsPages.ts`](src/docs/docsPages.ts) is
-the registry and the sidebar order.
+The documentation is markdown under [`src/docs/`](src/docs), served by the demo
+site. There is one page per topic, each holding the prose, its demos and a
+reference table. [`docsPages.ts`](src/docs/docsPages.ts) is the registry and the
+sidebar order.
 
 | Section              | Pages                                                            |
 | -------------------- | ---------------------------------------------------------------- |
@@ -109,10 +107,10 @@ is the demo site that documents it.
 
 | Path                | Contents                                                     |
 | ------------------- | ------------------------------------------------------------ |
-| `index.ts`          | The public API - the only entry point the package exposes     |
+| `index.ts`          | The public API, and the only entry point the package exposes  |
 | `useTMDataGrid.tsx` | The hook that builds the table, and the types it is built on  |
 | `core/`             | Headless logic: filtering, ordering, persistence, capabilities |
-| `components/`       | The React chrome and its co-located CSS modules               |
+| `components/`       | The React components and their co-located CSS modules         |
 
 ### Examples
 
@@ -122,14 +120,14 @@ The demo site's examples live in [`src/examples/`](src/examples):
 | ----------------- | -------------------------------------------------------------- |
 | `demoRegistry.ts` | Pairs each demo module with its own source through `import.meta.glob` |
 | `demos/`          | One file per demo: one idea, no headings, no explanation        |
-| `data/`           | Shared datasets, and the column set for demos about other things |
-| `playground/`     | The kitchen sink, every feature at once behind switches          |
+| `data/`           | Shared datasets, and the column set used by unrelated demos     |
+| `playground/`     | Every feature at once, behind switches                          |
 
-Adding a demo is adding a file under `demos/` and naming it from a ` ```demo `
-fence on the docs page that explains it. The registry pairs each module with
-its own source, so the code on screen cannot drift from the code running.
-[`demos.test.tsx`](src/examples/demos.test.tsx) mounts every registered demo,
-so a demo that stops working fails the suite whether or not it still compiles.
+To add a demo, add a file under `demos/` and name it from a ` ```demo ` fence on
+the docs page that explains it. The registry pairs each module with its own
+source, so the code on screen cannot drift from the code running.
+[`demos.test.tsx`](src/examples/demos.test.tsx) mounts every registered demo, so
+a demo that stops working fails the suite whether or not it still compiles.
 
 ```sh
 npm install
@@ -141,8 +139,8 @@ npm run test:watch
 
 ## Testing
 
-For testing an application that *uses* the grid - the test ids, roles and ARIA
-attributes it publishes, and how to drive it from Playwright - see
+For testing an application that *uses* the grid, including the test ids, roles
+and ARIA attributes it publishes and how to drive it from Playwright, see
 [Testing](src/docs/testing.md). What follows is about this repo's own suite.
 
 Vitest with React Testing Library, in jsdom. Tests sit next to the code they
@@ -150,11 +148,11 @@ cover as `*.test.ts(x)` and are excluded from both the package and the
 declaration build; shared fixtures live in [`src/test/`](src/test) so they stay
 out of `src/tmdatagrid/` entirely.
 
-Two things worth knowing before adding to them:
+Two things to know before adding to them:
 
-- `vitest.setup.ts` installs what jsdom does not provide - an in-memory
-  `Storage`, `matchMedia`, `ResizeObserver`, and element sizes. The last one
-  matters: without a measurable box, the virtualizer renders no rows at all.
+- `vitest.setup.ts` installs what jsdom does not provide: an in-memory
+  `Storage`, `matchMedia`, `ResizeObserver`, and element sizes. Element sizes
+  matter, because without a measurable box the virtualizer renders no rows.
 - The Mantine provider in the harness runs with `env="test"`, which disables
   transitions. Without it a popover never finishes mounting and its panel is
   never found.
@@ -183,8 +181,8 @@ works everywhere without putting `.js` extensions in the sources.
 ## Publishing
 
 Releases are managed by [Changesets](https://github.com/changesets/changesets).
-Nothing publishes from an ordinary push - a release happens only when the
-version PR is merged.
+Nothing publishes from an ordinary push. A release happens only when the version
+PR is merged.
 
 Describe your change in the same PR that makes it:
 
@@ -196,9 +194,9 @@ That writes a markdown file under `.changeset/`. Commit it alongside the code.
 
 Once on `main`, [`release.yml`](.github/workflows/release.yml) opens a
 **chore: version packages** PR that collects every pending changeset, bumps
-`package.json`, writes `CHANGELOG.md` and syncs the skills. The PR is the
-release proposal: review the version it picked and the changelog it wrote, then
-merge it to publish to npm with provenance.
+`package.json`, writes `CHANGELOG.md` and syncs the skills. Review the version it
+picked and the changelog it wrote, then merge it to publish to npm with
+provenance.
 
 The package build runs from `prepublishOnly` rather than as a workflow step, so
 `npm publish` cannot ship a stale `dist` whether it runs in CI or by hand.
@@ -212,7 +210,7 @@ The package build runs from `prepublishOnly` rather than as a workflow step, so
 Intent reports a skill as stale when its `library_version` trails the package
 version, so without that step every release would leave every skill stale.
 Because it runs inside the version command, the bump and the skill sync land in
-the same PR and are reviewed together.
+the same PR.
 
 To check what a release would contain without publishing anything:
 

package/dist/index.d.ts

@@ -61,7 +61,7 @@ type TMDataGridEditActionsProps = {
 /**
  * Batch mode's toolbar chrome: Save with the dirty-row count, and Discard.
  * Both read the edit store, so they grey out while nothing is dirty and the
- * Save spins while a submit is in flight. Works under any `editMode` - a
+ * Save spins while a submit is in flight. Works under any `editing.mode` - a
  * cellConfirm grid accumulating drafts can offer the same pair - and renders
  * nothing while editing is off.
  *
@@ -204,9 +204,9 @@ declare function optionsToComboboxData(options: ReadonlyArray<TMDataGridOption>)
  * The value shape stored in `columnFilters` for every TMDataGrid column.
  *
  * TanStack resolves `filterFn` statically per column, so the operator travels
- * inside the filter *value* instead. That keeps the whole filter model plain,
- * serialisable JSON - which is what makes it portable to a server-side
- * `manualFiltering` table (just forward `columnFilters` to the API).
+ * inside the filter *value* instead. That keeps the filter model plain,
+ * serialisable JSON, so a server-side `manualFiltering` table can forward
+ * `columnFilters` to the API unchanged.
  *
  * `value` is a string array under `isAnyOf` / `isNoneOf` (the set the cell is
  * tested against), a `[min, max]` pair under `between` (an empty string means
@@ -505,11 +505,11 @@ type TMDataGridEditCommitBatchArgs<TData extends RowData> = {
  * The data path a column edits, or `null` for a column that has none.
  *
  * `accessorKey` is the true path and Form addresses fields by dot-path, so
- * nested rows work for free: `accessorKey: "address.city"` edits
- * `values.address.city`. A column built on `accessorFn` has no path and is
- * not editable unless `meta.edit.field` names one. TanStack's default column
- * id turns dots into underscores - which is why this starts from
- * `accessorKey`, never from `id`.
+ * nested rows need no extra handling: `accessorKey: "address.city"` edits
+ * `values.address.city`. A column built on `accessorFn` has no path and is not
+ * editable unless `meta.edit.field` names one. TanStack's default column id
+ * turns dots into underscores, which is why this starts from `accessorKey` and
+ * never from `id`.
  */
 declare function getEditFieldName(column: {
   columnDef: {
@@ -819,11 +819,11 @@ type GridState = TableState<TMDataGridFeatures>;
 /**
  * Persistence deliberately does not use Mantine's `useLocalStorage`.
  *
- * That hook owns a piece of state and returns `[value, setValue]`. Here the
- * table already owns the state and storage only mirrors it, so routing writes
+ * That hook holds a piece of state and returns `[value, setValue]`. Here the
+ * table already holds the state and storage only mirrors it, so routing writes
  * through the hook would keep a second copy and trigger a React state update on
  * every change, including every pointer move during a column resize. Its
- * defaults also work against this use: `getInitialValueInEffect: true` delivers
+ * defaults also conflict with this use: `getInitialValueInEffect: true` delivers
  * the stored value after mount, while `initialState` is only read on the first
  * render, and `sync: true` would let two open tabs overwrite each other's
  * column layout.
@@ -983,7 +983,7 @@ type TMDataGridFeatureFlags = {
    * its own grouping can still say `enableGrouping: true` to override.
    */
   grouping: boolean;
-  /** Whether cells can be edited at all - `editMode` was set. */
+  /** Whether cells can be edited at all - the `editing` option was set. */
   editing: boolean;
   /** The commit policy, or `null` while editing is off. */
   editMode: TMDataGridEditMode | null;
@@ -1003,7 +1003,7 @@ type TMDataGridFeatureFlags = {
    */
   matchHighlighting: boolean;
 };
-declare function readFeatureFlags<TData extends RowData>(options: Pick<UseTMDataGridOptions<TData>, "enableSorting" | "enableColumnFilters" | "enableGlobalFilter" | "enableHiding" | "enableColumnPinning" | "enableColumnResizing" | "enableColumnOrdering" | "enableRowSelection" | "enableMultiRowSelection" | "selectionMode" | "showSelectedBackground" | "cellSelection" | "enablePagination" | "manualPagination" | "enableGrouping" | "editMode" | "enableRowNumbers" | "enableRowPinning" | "enableMatchHighlighting">): TMDataGridFeatureFlags;
+declare function readFeatureFlags<TData extends RowData>(options: Pick<UseTMDataGridOptions<TData>, "enableSorting" | "enableColumnFilters" | "enableGlobalFilter" | "enableHiding" | "enableColumnPinning" | "enableColumnResizing" | "enableColumnOrdering" | "enableRowSelection" | "enableMultiRowSelection" | "selectionMode" | "showSelectedBackground" | "cellSelection" | "enablePagination" | "manualPagination" | "enableGrouping" | "editing" | "enableRowNumbers" | "enableRowPinning" | "enableMatchHighlighting">): TMDataGridFeatureFlags;
 /**
  * What one column's header may offer.
  *
@@ -1049,8 +1049,8 @@ declare function getGridCapabilities(table: TMDataGridTable<TMDataGridRowData>,
  * Ids, because every other thing the grid does moves cells around: sorting
  * reorders rows, filtering removes them, dragging a header reorders columns. A
  * coordinate pair would silently come to mean a different cell after any of
- * them, while a pair of ids either still resolves or does not resolve at all -
- * and "does not resolve" is a state the grid can handle honestly.
+ * them, while a pair of ids either still resolves or does not resolve at all,
+ * and the grid handles "does not resolve" explicitly.
  *
  * Indices are what navigation is actually computed in, so they are resolved
  * from the ids on each keystroke and turned straight back. See resolveCellMove.
@@ -1129,11 +1129,11 @@ type ResolveRangeBoundsArgs = {
  * Turns a range into the rectangle to paint and copy, or `null` when either
  * corner no longer exists.
  *
- * A corner goes missing whenever a filter drops its row or a column is hidden,
- * and the honest answer then is that there is no rectangle - better than
- * guessing at a replacement corner and quietly copying cells the user never
- * selected. The range itself is left alone: clearing it here would throw away
- * a selection that comes straight back when the filter is lifted.
+ * A corner goes missing whenever a filter drops its row or a column is hidden.
+ * There is then no rectangle, rather than a guessed replacement corner that
+ * would copy cells the user never selected. The range itself is left alone:
+ * clearing it here would discard a selection that returns as soon as the filter
+ * is cleared.
  */
 declare function resolveRangeBounds({ range, rowIndexOf, columnIndexOf }: ResolveRangeBoundsArgs): TMDataGridRangeBounds | null;
 /** Whether a cell is inside the rectangle. */
@@ -1141,7 +1141,7 @@ declare function isWithinBounds(bounds: TMDataGridRangeBounds | null, rowIndex:
 /** How many cells the rectangle covers. `0` for no range at all. */
 declare function boundsCellCount(bounds: TMDataGridRangeBounds | null): number;
 /**
- * Which edges of the rectangle a cell sits on, for the outline.
+ * Which edges of the rectangle a cell lies on, for the outline.
  *
  * The border is drawn per cell rather than as one box over the top, because the
  * body is a scrolling CSS grid with sticky columns in it: an overlay would have
@@ -1157,14 +1157,14 @@ declare function boundsEdges(bounds: TMDataGridRangeBounds | null, rowIndex: num
 //#endregion
 //#region .types-tmp/useTMDataGrid.d.ts
 /**
- * Per-column configuration the TMDataGrid chrome reads.
+ * Per-column configuration the grid's own components read.
  *
- * A stage that owns behaviour gets a namespace - `filter` and `edit`, each
+ * The filter and edit stages each get a namespace, `filter` and `edit`,
  * mirroring the feature's runtime API. What the column *is* stays flat:
  * `label`, `type`, `options`, `align`, `flex`, `autoSize`, `enableOrdering`.
- * `type` and `options` in particular are shared ground - one declaration of
- * each feeds the filter panel and the cell editor alike, which is why they sit
- * outside both namespaces.
+ * `type` and `options` are read by both stages, so one declaration of each
+ * feeds the filter panel and the cell editor, which is why they sit outside
+ * both namespaces.
  */
 type TMDataGridColumnMeta = {
   /** Name shown in menus and the column manager. Falls back to a string header. */
@@ -1515,7 +1515,7 @@ type TMDataGridApi<TData extends RowData> = {
    * The edit engine - open forms, dirty/error projections, and the verbs
    * (`begin`, `commit`, `cancel`, `submitAll`). `edit.getForm(rowId)` hands
    * out the same TanStack Form the inline editors write through, so a drawer
-   * or detail panel can share a row's draft. Inert until `editMode` is set.
+   * or detail panel can share a row's draft. Inert until `editing` is set.
    */
   edit: TMDataGridEditApi;
   /** Table-level feature switches, re-read from options on every render. */
@@ -1558,19 +1558,13 @@ type TMDataGridApi<TData extends RowData> = {
    */
   scrollToRow: (args: TMDataGridScrollToRowArgs) => boolean;
   /**
-   * @internal Wiring for `TMDataGrid.Table`, which owns the virtualizer and
-   * fills this in. Not part of the supported surface.
+   * @internal Wiring for `TMDataGrid.Table`, which holds the virtualizer and
+   * fills this in. Not part of the public API.
    */
   scrollerRef: MutableRefObject<TMDataGridScroller>;
 };
-/** The editing callbacks every mode shares. See {@link TMDataGridEditingOptions}. */
+/** The editing members every mode shares. See {@link TMDataGridEditingOptions}. */
 type TMDataGridEditingCallbacks<TData extends RowData> = {
-  /**
-   * `getRowId` stops being optional once editing is on: the forms are keyed
-   * by row id and live outside the DOM, and the index fallback points at a
-   * different record after any sort.
-   */
-  getRowId: NonNullable<TableOptions<TMDataGridFeatures, TData>["getRowId"]>;
   /**
    * Form-level validators for the whole editing row - where cross-field
    * rules live. TanStack Form's own vocabulary, Standard Schema included:
@@ -1596,10 +1590,10 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
    * draft visible with a busy marker - and a rejection keeps the form open
    * with the error on the row.
    *
-   * `changes` is the per-field diff (one entry in cell mode) for consumers
-   * who PATCH; `value` is the whole edited row for those who save records.
+   * `changes` is the per-field diff (one entry in cell mode), for a PATCH.
+   * `value` is the entire edited row, for saving a record.
    */
-  onEditCommit?: (args: TMDataGridEditCommitArgs<TData>) => void | Promise<void>;
+  onCommit?: (args: TMDataGridEditCommitArgs<TData>) => void | Promise<void>;
   /**
    * Seed values for `edit.addRow()` - the entry row's starting point. A
    * function is called per added row (fresh timestamps, empty arrays).
@@ -1620,14 +1614,9 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
   onRowDelete?: (args: TMDataGridRowDeleteArgs<TData>) => void | Promise<void>;
 };
 /**
- * The editing options travel together, and the type states it: without
- * `editMode` none of them has anything to act on, so passing one is a
- * compile error rather than a dead option; with it, `getRowId` becomes
- * required; and `onEditCommitBatch` exists only under `"batch"` - the one
- * mode whose `submitAll` calls it.
- *
- * `editMode` itself turns cell editing on and picks how commits happen. Off
- * by default.
+ * The `editing` option: one object that turns editing on and holds
+ * everything about it. `mode` picks what counts as a commit and which
+ * controls trigger it; the other members act within that mode.
  *
  * | Mode | Commit | Cancel |
  * | ---- | ------ | ------ |
@@ -1636,36 +1625,46 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
  * | `"row"` | Save in the edit lane, or Ctrl+Enter | Cancel, or Escape |
  * | `"batch"` | `edit.submitAll()` | `edit.cancelAll()` |
  *
+ * Setting `editing` makes `getRowId` required - drafts are keyed by row id,
+ * and the index fallback would name a different record after any sort - and
+ * `onCommitBatch` exists only under `mode: "batch"`, the one mode whose
+ * `submitAll` calls it.
+ *
+ * The object may be written inline: the callbacks are read through a ref
+ * every render, so its identity does not matter.
+ *
  * One TanStack Form per editing row; drafts survive scrolling because the
  * forms live outside the DOM, keyed by row id. Which columns edit, and with
  * what, is declared per column under `meta.edit`: `meta.type` picks the
  * built-in editor, and `enabled`, `field`, `editor`, `validate` and `mapValue`
  * override the rest.
  */
-type TMDataGridEditingOptions<TData extends RowData> = (TMDataGridEditingCallbacks<TData> & {
-  editMode: "batch";
+type TMDataGridEditingOptions<TData extends RowData> = TMDataGridEditingCallbacks<TData> & ({
+  mode: "batch";
   /**
    * Batch mode's save, called once by `edit.submitAll()` with every
    * valid dirty row. Without it, `submitAll` falls back to the per-row
-   * {@link TMDataGridEditingCallbacks.onEditCommit} loop. Rows failing
+   * {@link TMDataGridEditingCallbacks.onCommit} loop. Rows failing
    * validation stay open either way; a rejection keeps every draft.
    */
-  onEditCommitBatch?: (args: TMDataGridEditCommitBatchArgs<TData>) => void | Promise<void>;
-}) | (TMDataGridEditingCallbacks<TData> & {
-  editMode: Exclude<TMDataGridEditMode, "batch">;
+  onCommitBatch?: (args: TMDataGridEditCommitBatchArgs<TData>) => void | Promise<void>;
+} | {
+  mode: Exclude<TMDataGridEditMode, "batch">;
   /** Only `"batch"`'s `submitAll` ever calls it - see the other branch. */
-  onEditCommitBatch?: never;
-}) | {
-  editMode?: never;
-  rowValidators?: never;
-  isRowEditable?: never;
-  onEditCommit?: never;
-  onEditCommitBatch?: never;
-  newRowDefaults?: never;
-  onRowAdd?: never;
-  onRowDelete?: never;
-};
-type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridFeatures, TData>, "features"> & TMDataGridEditingOptions<TData> & {
+  onCommitBatch?: never;
+});
+type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridFeatures, TData>, "features"> & ({
+  editing?: undefined;
+} | {
+  /** Turns editing on. See {@link TMDataGridEditingOptions}. */
+  editing: TMDataGridEditingOptions<TData>;
+  /**
+   * Required once `editing` is set: the forms are keyed by row id and
+   * live outside the DOM, and the index fallback points at a different
+   * record after any sort.
+   */
+  getRowId: NonNullable<TableOptions<TMDataGridFeatures, TData>["getRowId"]>;
+}) & {
   /**
    * Restore and persist table state across mounts. Two keys, because the two
    * kinds of state have different lifetimes - see {@link TMDataGridPersistence}.
@@ -1885,9 +1884,9 @@ type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridF
    * Defaults to 160.
    *
    * An estimate, not a height: every mounted row is measured, so the real one
-   * takes over as soon as the panel is on screen. It keeps the scrollbar honest
-   * for panels that open off screen (restored `expanded` state, say), and being
-   * roughly right is enough.
+   * takes over as soon as the panel is on screen. It keeps the scrollbar
+   * accurate for panels that open off screen, such as restored `expanded`
+   * state. An approximate value is enough.
    */
   renderDetailsEstHeight?: number;
   /**
@@ -1911,7 +1910,7 @@ type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridF
  * flag on, so `<TMDataGrid.Footer />` renders its pager without further
  * options.
  */
-declare function useTMDataGrid<TData extends RowData>({ persist, labels: labelsOverride, enableColumnOrdering, enablePagination, enableRowNumbers, selectionMode, showSelectedBackground, defaultHighlightedRowId, onHighlightedRowChange, cellSelection, onFocusedCellChange, editMode, rowValidators, isRowEditable, onEditCommit, onEditCommitBatch, newRowDefaults, onRowAdd, onRowDelete, renderDetails, renderDetailsEstHeight, overscan, ...options }: UseTMDataGridOptions<TData>): TMDataGridApi<TData>;
+declare function useTMDataGrid<TData extends RowData>({ persist, labels: labelsOverride, enableColumnOrdering, enablePagination, enableRowNumbers, selectionMode, showSelectedBackground, defaultHighlightedRowId, onHighlightedRowChange, cellSelection, onFocusedCellChange, editing, renderDetails, renderDetailsEstHeight, overscan, ...options }: UseTMDataGridOptions<TData>): TMDataGridApi<TData>;
 /**
  * Opens the filter panel for a column, seeding an empty filter row when the
  * column has none yet - mirrors "Filter" in the column header menu.
@@ -2213,9 +2212,9 @@ declare function toClipboardText(matrix: TMDataGridCellMatrix): string;
  * | UTF-8 BOM | without it Excel reads the file as ANSI, and å ä ö arrive broken |
  * | CRLF line endings | what Excel writes, and what its importer is happiest with |
  *
- * The `sep=` line is Excel's alone; other readers show it as a first row. That
- * is the trade this makes - the file is for Excel, and "it just opens" is worth
- * more than being a well-behaved CSV nobody was going to feed to a parser.
+ * The `sep=` line is Excel's alone; other readers show it as a first row. This
+ * export targets Excel, so opening correctly there takes priority over strict
+ * CSV.
  */
 declare function toExcelCsv(matrix: TMDataGridCellMatrix, { separator }: {
   separator: string;
@@ -2226,7 +2225,7 @@ declare function toExcelCsv(matrix: TMDataGridCellMatrix, { separator }: {
  * The async clipboard API only resolves for a document that has the focus and a
  * user gesture behind it - both true when this runs off Ctrl+C or a menu item.
  * It is still allowed to reject (a permissions policy, a page that lost focus
- * mid-copy), so the result is a boolean rather than a promise nobody checks.
+ * mid-copy), so the result is a boolean the caller can act on.
  */
 declare function writeClipboardText(text: string): Promise<boolean>;
 /**
@@ -2473,9 +2472,9 @@ type TMDataGridTableProps<TData extends RowData> = {
    */
   reachEndThreshold?: number;
   /**
-   * Accessible name for the grid - what a screen reader announces on entry,
-   * and what `getByRole("grid", { name })` matches. Worth setting on any page
-   * holding more than one grid; without it they are all just "grid".
+   * Accessible name for the grid: what a screen reader announces on entry, and
+   * what `getByRole("grid", { name })` matches. Set it on any page holding more
+   * than one grid; without it they are all announced as "grid".
    */
   "aria-label"?: string;
   /** As {@link "aria-label"}, pointing at an element that already names it. */
@@ -2483,9 +2482,9 @@ type TMDataGridTableProps<TData extends RowData> = {
 };
 /**
  * The scrollable grid surface. Always virtualized: only the rows inside the
- * viewport (plus overscan) are mounted - which is what makes the default
- * no-pagination mode viable at any row count. Pagination is opt-in via
- * `enablePagination` (or implied by `manualPagination`).
+ * viewport (plus overscan) are mounted, which is what makes the default
+ * no-pagination mode work at any row count. Pagination is opt in through
+ * `enablePagination`, or implied by `manualPagination`.
  */
 declare function TMDataGridTable$1<TData extends RowData = TMDataGridRowData>({ onRowClick, onCellClick, onCellDoubleClick, onCellContextMenu, rowClassName, rowStyle, striped, onScrollToTop, onScrollToBottom, onScrollToLeft, onScrollToRight, renderEmptyState, renderRowContextMenu, renderColumnMenuItems, rowContextMenuProps, cellExport, onReachEnd, reachEndThreshold, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy }: TMDataGridTableProps<TData>): import("react").JSX.Element;
 //#endregion
@@ -2775,6 +2774,16 @@ declare function isColumnEditableForRow(column: ColumnLike, row: Row<TMDataGridF
  * chevron, and wants the padding.
  */
 declare function isControlColumn(columnId: string): boolean;
+/**
+ * Whether the grid generated this column rather than the consumer declaring it
+ * - the four control lanes plus the tree column.
+ *
+ * These hold the grid's own chrome, and they keep the edges of the row: the
+ * generated left lanes before every consumer column, the edit lane after all of
+ * them. `isControlColumn` answers a narrower question about layout, and leaves
+ * the tree column out because it is padded like a data column.
+ */
+declare function isGeneratedColumn(columnId: string): boolean;
 /**
  * Whether a column may be moved. Ordering is the one column feature TanStack
  * has no column option for, so the switch lives in `meta.enableOrdering`.
@@ -2829,7 +2838,9 @@ declare function aggregateColumn<TData extends RowData>({ table, columnId, fn }:
  *
  * Mounted cells only: under virtualization the unmounted rows do not exist to
  * be measured, so this reads the visible window plus overscan - the same
- * trade AG Grid's autosize makes by default.
+ * trade AG Grid's autosize makes by default. With no rows mounted at all the
+ * header is the only thing left to measure, which is a width that fits the
+ * title and nothing else - see `hasMountedCells`.
  */
 declare function measureColumnContentWidth({ container, columnId }: {
   /** The grid's scroll container - anything enclosing the column's cells. */
@@ -2928,6 +2939,20 @@ type MoveColumnArgs = {
  * updates that array as well.
  */
 declare function moveColumn({ table, columnId, targetId, side }: MoveColumnArgs): void;
+/**
+ * Puts the generated lanes back on the outside of both pinned lanes: the ones
+ * on the left before every consumer column, the edit lane after all of them.
+ *
+ * `column.pin("right")` appends, so pinning a column right would otherwise drop
+ * it outside the edit lane, so the row's Save and Delete would no longer be
+ * last in the row. Pinning left appends too, which is already correct there,
+ * but the same pass keeps both lanes in place whatever a consumer writes into
+ * `columnPinning` directly.
+ *
+ * Relative order is preserved inside each part, so a user's own arrangement of
+ * the pinned columns survives.
+ */
+declare function keepGeneratedColumnsOutermost(pinning: ColumnPinningState): ColumnPinningState;
 type ColumnStepArgs = {
   table: GridTable;
   columnId: string;
@@ -2998,9 +3023,9 @@ type ResolveRowSelectionClickArgs<TData extends RowData> = {
   /**
    * Whether this gesture is allowed to clear rows it did not touch.
    *
-   * `true` for a bare row click, where replacing is the whole point. `false` for
-   * a checkbox, which is only ever additive - ticking one box has never cleared
-   * the others, and shift-clicking one adds the range rather than becoming it.
+   * `true` for a bare row click, which replaces the selection. `false` for a
+   * checkbox, which is only ever additive: ticking one box does not clear the
+   * others, and shift-clicking one adds the range rather than replacing it.
    */
   canReplaceSelection: boolean;
 };
@@ -3044,4 +3069,4 @@ declare function getSelectableRowIds<TData extends RowData>(row: Row<TMDataGridF
  */
 declare function resolveRowSelectionClick<TData extends RowData>({ rows, rowId, anchorRowId, modifiers, selection, canReplaceSelection }: ResolveRowSelectionClickArgs<TData>): ResolvedRowSelection;
 //#endregion
-export { type BuildCellMatrixArgs, type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_CELL_EXPORT_OPTIONS, DEFAULT_TMDATAGRID_SIZE, DETAILS_COLUMN_ID, DgAutocompleteFilter, DgDateRangeFilter, DgRangeSliderFilter, DgTriStateFilter, EDIT_COLUMN_ID, FILTER_OPERATOR_LABELS, GROUP_COLUMN_ID, type MoveColumnArgs, PERSIST_PAYLOAD_VERSION, ROW_NUMBER_COLUMN_ID, type ResolveCellMoveArgs, type ResolveRangeBoundsArgs, type ResolveRowSelectionClickArgs, type ResolvedRowSelection, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDATAGRID_LABELS_EN, TMDATAGRID_LABELS_SV, TMDataGrid, type TMDataGridAggregationName, type TMDataGridApi, TMDataGridBooleanEditor, type TMDataGridCapabilities, type TMDataGridCellCoords, type TMDataGridCellEventArgs, type TMDataGridCellExportOptions, type TMDataGridCellMatrix, type TMDataGridCellNav, type TMDataGridCellPosition, type TMDataGridCellRange, type TMDataGridCellSelectionMode, type TMDataGridColumnCapabilities, type TMDataGridColumnEditOptions, type TMDataGridColumnFilterOptions, type TMDataGridColumnLayout, type TMDataGridColumnMenuItemsArgs, type TMDataGridColumnMenuItemsRenderer, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnType, type TMDataGridContextValue, type TMDataGridDataSlice, TMDataGridDateEditor, type TMDataGridDetailsArgs, type TMDataGridDetailsRenderer, type TMDataGridDropSide, TMDataGridEditActions, type TMDataGridEditActionsActions, type TMDataGridEditActionsControls, type TMDataGridEditActionsProps, type TMDataGridEditActionsSlotArgs, type TMDataGridEditActionsState, type TMDataGridEditApi, type TMDataGridEditChange, type TMDataGridEditCommitArgs, type TMDataGridEditCommitBatchArgs, type TMDataGridEditField, type TMDataGridEditMode, type TMDataGridEditRowProjection, type TMDataGridEditState, type TMDataGridEditValueMap, type TMDataGridEditValueMapArgs, type TMDataGridEditingOptions, type TMDataGridEditorArgs, type TMDataGridEditorComponent, type TMDataGridExpandAllArgs, type TMDataGridExpandTarget, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFieldValidate, type TMDataGridFilterControlArgs, type TMDataGridFilterControlComponent, type TMDataGridFilterOperator, TMDataGridFilterPills, type TMDataGridFilterPillsProps, type TMDataGridFilterValue, TMDataGridFilterValueInput, type TMDataGridFooterProps, type TMDataGridLabels, type TMDataGridLabelsOverride, TMDataGridMultiSelectEditor, TMDataGridNumberEditor, type TMDataGridOption, type TMDataGridOptionsArgs, type TMDataGridOptionsSource, type TMDataGridPaginationActions, type TMDataGridPaginationApi, type TMDataGridPaginationControls, type TMDataGridPaginationSlotArgs, type TMDataGridPaginationState, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridQuickSearchMode, type TMDataGridRangeBounds, type TMDataGridRowAddArgs, type TMDataGridRowClickModifiers, type TMDataGridRowContextMenuArgs, type TMDataGridRowContextMenuRenderer, type TMDataGridRowData, type TMDataGridRowDeleteArgs, type TMDataGridRowEditForm, type TMDataGridRowStyle, type TMDataGridRowValidators, type TMDataGridScrollAlign, type TMDataGridScrollToRowArgs, TMDataGridSearch, type TMDataGridSearchProps, TMDataGridSelectEditor, type TMDataGridSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, TMDataGridStringEditor, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridTableProps, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, aggregateColumn, areAllRowsExpanded, autosizeColumn, boundsCellCount, boundsEdges, buildCellMatrix, buildGridCellMatrix, clearedValueForType, createTMDataGridColumnHelper, downloadTextFile, emptyValueForOperator, exportGridToCsv, formatExportValue, formatFilterLabel, formatGroupValue, fuzzyGlobalFilterFn, getColumnCapabilities, getColumnDefaultOperator, getColumnFilterControl, getColumnLabel, getColumnRegion, getColumnType, getDefaultOperator, getDisplayedRows, getEditFieldName, getGridCapabilities, getGroupDataRows, getOperatorsForType, getSelectableRowIds, getStepTargetColumn, getTMDataGridPaginationApi, isColumnEditableForRow, isColumnReorderable, isControlColumn, isFilterActive, isPagingActive, isSameCell, isWithinBounds, measureColumnContentWidth, mergeLabels, moveColumn, moveColumnByStep, normalizeFieldValidate, openColumnFilter, operatorNeedsValue, operatorTakesArrayValue, operatorTakesRangeValue, optionsToComboboxData, readFeatureFlags, resolveCellMove, resolveColumnOptions, resolveExpandAll, resolveRangeBounds, resolveRowSelectionClick, tmDataGridFeatures, toClipboardText, toExcelCsv, useCellControlTabIndex, useTMDataGrid, useTMDataGridContext, writeClipboardText };
+export { type BuildCellMatrixArgs, type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_CELL_EXPORT_OPTIONS, DEFAULT_TMDATAGRID_SIZE, DETAILS_COLUMN_ID, DgAutocompleteFilter, DgDateRangeFilter, DgRangeSliderFilter, DgTriStateFilter, EDIT_COLUMN_ID, FILTER_OPERATOR_LABELS, GROUP_COLUMN_ID, type MoveColumnArgs, PERSIST_PAYLOAD_VERSION, ROW_NUMBER_COLUMN_ID, type ResolveCellMoveArgs, type ResolveRangeBoundsArgs, type ResolveRowSelectionClickArgs, type ResolvedRowSelection, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDATAGRID_LABELS_EN, TMDATAGRID_LABELS_SV, TMDataGrid, type TMDataGridAggregationName, type TMDataGridApi, TMDataGridBooleanEditor, type TMDataGridCapabilities, type TMDataGridCellCoords, type TMDataGridCellEventArgs, type TMDataGridCellExportOptions, type TMDataGridCellMatrix, type TMDataGridCellNav, type TMDataGridCellPosition, type TMDataGridCellRange, type TMDataGridCellSelectionMode, type TMDataGridColumnCapabilities, type TMDataGridColumnEditOptions, type TMDataGridColumnFilterOptions, type TMDataGridColumnLayout, type TMDataGridColumnMenuItemsArgs, type TMDataGridColumnMenuItemsRenderer, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnType, type TMDataGridContextValue, type TMDataGridDataSlice, TMDataGridDateEditor, type TMDataGridDetailsArgs, type TMDataGridDetailsRenderer, type TMDataGridDropSide, TMDataGridEditActions, type TMDataGridEditActionsActions, type TMDataGridEditActionsControls, type TMDataGridEditActionsProps, type TMDataGridEditActionsSlotArgs, type TMDataGridEditActionsState, type TMDataGridEditApi, type TMDataGridEditChange, type TMDataGridEditCommitArgs, type TMDataGridEditCommitBatchArgs, type TMDataGridEditField, type TMDataGridEditMode, type TMDataGridEditRowProjection, type TMDataGridEditState, type TMDataGridEditValueMap, type TMDataGridEditValueMapArgs, type TMDataGridEditingOptions, type TMDataGridEditorArgs, type TMDataGridEditorComponent, type TMDataGridExpandAllArgs, type TMDataGridExpandTarget, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFieldValidate, type TMDataGridFilterControlArgs, type TMDataGridFilterControlComponent, type TMDataGridFilterOperator, TMDataGridFilterPills, type TMDataGridFilterPillsProps, type TMDataGridFilterValue, TMDataGridFilterValueInput, type TMDataGridFooterProps, type TMDataGridLabels, type TMDataGridLabelsOverride, TMDataGridMultiSelectEditor, TMDataGridNumberEditor, type TMDataGridOption, type TMDataGridOptionsArgs, type TMDataGridOptionsSource, type TMDataGridPaginationActions, type TMDataGridPaginationApi, type TMDataGridPaginationControls, type TMDataGridPaginationSlotArgs, type TMDataGridPaginationState, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridQuickSearchMode, type TMDataGridRangeBounds, type TMDataGridRowAddArgs, type TMDataGridRowClickModifiers, type TMDataGridRowContextMenuArgs, type TMDataGridRowContextMenuRenderer, type TMDataGridRowData, type TMDataGridRowDeleteArgs, type TMDataGridRowEditForm, type TMDataGridRowStyle, type TMDataGridRowValidators, type TMDataGridScrollAlign, type TMDataGridScrollToRowArgs, TMDataGridSearch, type TMDataGridSearchProps, TMDataGridSelectEditor, type TMDataGridSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, TMDataGridStringEditor, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridTableProps, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, aggregateColumn, areAllRowsExpanded, autosizeColumn, boundsCellCount, boundsEdges, buildCellMatrix, buildGridCellMatrix, clearedValueForType, createTMDataGridColumnHelper, downloadTextFile, emptyValueForOperator, exportGridToCsv, formatExportValue, formatFilterLabel, formatGroupValue, fuzzyGlobalFilterFn, getColumnCapabilities, getColumnDefaultOperator, getColumnFilterControl, getColumnLabel, getColumnRegion, getColumnType, getDefaultOperator, getDisplayedRows, getEditFieldName, getGridCapabilities, getGroupDataRows, getOperatorsForType, getSelectableRowIds, getStepTargetColumn, getTMDataGridPaginationApi, isColumnEditableForRow, isColumnReorderable, isControlColumn, isFilterActive, isGeneratedColumn, isPagingActive, isSameCell, isWithinBounds, keepGeneratedColumnsOutermost, measureColumnContentWidth, mergeLabels, moveColumn, moveColumnByStep, normalizeFieldValidate, openColumnFilter, operatorNeedsValue, operatorTakesArrayValue, operatorTakesRangeValue, optionsToComboboxData, readFeatureFlags, resolveCellMove, resolveColumnOptions, resolveExpandAll, resolveRangeBounds, resolveRowSelectionClick, tmDataGridFeatures, toClipboardText, toExcelCsv, useCellControlTabIndex, useTMDataGrid, useTMDataGridContext, writeClipboardText };