@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/features/data-source.md

@@ -1,15 +1,17 @@
 # 🌐 Server-Side Data Source
 
-Handle millions of rows by connecting OpenGridX directly to your backend API.
+Connect OpenGridX to your backend API so the server does the sorting, filtering and paging.
 
 ---
 
 ## 📑 The `GridDataSource` Interface
 
-The `dataSource` prop is the gateway to server-side operations. When provided, the grid becomes a "thin client" that requests only the data it needs to render the current viewport.
+The `dataSource` prop is the gateway to server-side operations. The grid calls `getRows` with a row range and the current sort, filter and aggregation models, and shows the rows it returns. Requests are page-based (see *Modes of Operation*), not driven by the scroll position.
 
 ### Implementation
 ```tsx
+import { DataGrid, type GridDataSource } from '@opencorestack/opengridx';
+
 const myDataSource: GridDataSource = {
   getRows: async (params) => {
     const { startRow, endRow, sortModel, filterModel } = params;
@@ -23,12 +25,20 @@ const myDataSource: GridDataSource = {
     
     return {
       rows: data.items,
-      rowCount: data.totalCount // Required for stable pagination
+      rowCount: data.totalCount // the total, used by the pager with paginationMode="server"
     };
   }
 };
 
-<DataGrid dataSource={myDataSource} />
+<DataGrid
+  rows={[]}
+  columns={columns}
+  dataSource={myDataSource}
+  pagination
+  paginationMode="server"
+  sortingMode="server"
+  filterMode="server"
+/>
 ```
 
 ---
@@ -38,28 +48,41 @@ const myDataSource: GridDataSource = {
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
 | `startRow` | `number` | The starting index of the requested range. |
-| `endRow` | `number` | The ending index (exclusive). |
+| `endRow` | `number` | The ending index (exclusive): return `rows.slice(startRow, endRow)`. `Number.MAX_SAFE_INTEGER` means "every row". |
 | `sortModel` | `GridSortItem[]` | Current sorting configuration. |
 | `filterModel` | `GridFilterModel` | Current filtering configuration. |
-| `groupKeys` | `string[]` | Active expansion path (used for server-side tree data). |
+| `groupKeys` | `string[]` | Path of the parent whose children are requested (server-side tree data); empty for top-level rows. |
+| `aggregationModel` | `GridAggregationModel \| undefined` | Current aggregation configuration, so the server can return `aggregationResults`. |
 
 ---
 
 ## 🔄 Modes of Operation
 
-### 1. Server-Side Pagination
-Set `paginationMode="server"`. The grid will request fresh data every time the page changes.
+The grid calls `getRows` whenever a `dataSource` is set. Rapid changes are collapsed into one request (300 ms debounce); the loading state shows from the moment a request is scheduled. Rows are keyed with `getRowId`.
+
+### 1. Client Pagination (default)
+With `paginationMode="client"` (the default) the grid requests every row once (`startRow: 0`, `endRow: Number.MAX_SAFE_INTEGER`) and pages them itself. With `sortingMode="server"` or `filterMode="server"` a sort or filter change requests every row again with the new model; client-side sorts and filters, and page changes, never refetch.
+
+### 2. Server-Side Pagination
+Set `paginationMode="server"`. Each page change requests `[page * pageSize, (page + 1) * pageSize)` and the response replaces the rows. Return `rowCount` so the pager knows the total.
 
-### 2. Infinite Loading
-Set `paginationMode="infinite"`. The grid will request the next "chunk" of data as the user scrolls near the bottom of the list.
+Row grouping turns pagination off (every group renders in one scrollable view). With `rowGroupingModel` set, a `paginationMode="server"` source is therefore asked for every row (`startRow: 0`, `endRow: Number.MAX_SAFE_INTEGER`) instead of the first page, and a development warning says so (v3.0+; before, only the first page was requested and the rest were unreachable).
 
-### 3. Server-Side Tree Data
-When `treeData` is enabled with a `dataSource`, OpenGridX will call `getRows` with `groupKeys`. You should return the children for that specific parent path.
+### 3. Infinite Loading
+Set `paginationMode="infinite"` and advance `paginationModel.page` (for example from `onRowsScrollEnd`). The grid requests the rows from the end of what is loaded up to the current page and appends them, so a page that moves on while a request is in flight never leaves a gap. See [Infinite Scroll](infinite-scroll.md).
+
+### 4. Server-Side Tree Data
+When `treeData` is enabled with a `dataSource`, top-level rows come from the normal request. A row with `serverChildrenCount > 0` shows an expand toggle; expanding it calls `getRows` with that row's path in `groupKeys` (and `startRow: 0`, `endRow: Number.MAX_SAFE_INTEGER`). Return that parent's children. With `filterMode="server"` / `sortingMode="server"` the returned rows are neither re-filtered nor re-sorted in the tree. When a refetch replaces the rows (page, sort, filter), the children of nodes that are still expanded are requested again. If a children request fails, the node collapses again and the error is logged; expanding it retries. (It does not show the grid-level error overlay.) `defaultGroupingExpansionDepth` counts a node with `serverChildrenCount > 0` as expandable, so the nodes within that depth (all of them with `-1`) start expanded and their children are requested right away (v3.0+; before, lazy nodes were never expanded by the default depth).
+
+### When a refetch happens
+Models are compared by content, so an inline `filterModel={{ items: [] }}` or a `dataSource={{ getRows }}` object recreated with the same `getRows` function does not refetch. A new `getRows` function does. A response for parameters that have changed in the meantime is discarded.
 
 ---
 
 ## 🛠️ Error Handling
-If your API call fails, you should throw an error or return a rejected promise. OpenGridX will automatically display the **Error Overlay** with a "Retry" button.
+If your API call fails, throw an error or return a rejected promise. OpenGridX shows the **Error Overlay** with the rejection's `message` (an `Error`, a string, or any object with a string `message`) and a **Retry** button that requests the rows again.
+
+A response the grid cannot use fails the same way (v3.0+): a response without a `rows` array, or a `getRowId` that throws for a fetched row, shows the error overlay and ends the loading state, instead of an unhandled promise rejection and an endless "Loading". For a children request (server-side tree data) it collapses the node as a failed request does.
 
 ```typescript
 getRows: async () => {

package/docs/features/editing-reordering.md

@@ -10,12 +10,33 @@ OpenGridX supports inline cell editing. For a column to be editable, you must se
 
 ### Basic Setup
 ```tsx
-const columns = [
+import type { GridColDef } from '@opencorestack/opengridx';
+
+const columns: GridColDef[] = [
   { field: 'name', editable: true },
   { field: 'role', editable: true, type: 'singleSelect', valueOptions: ['Admin', 'Editor'] }
 ];
 ```
 
+Double-click a cell or press **Enter** on a focused cell to open its editor.
+
+### Which cells can be edited
+A cell is editable when its column has `editable: true` **and**, if you pass it, `isCellEditable` returns `true`. The same rule drives double-click, Enter, the cells **Tab** stops on while editing, and `aria-readonly`.
+
+```tsx
+<DataGrid
+  columns={columns}
+  rows={rows}
+  // Lock archived rows, whatever the column says.
+  isCellEditable={({ row }) => row.status !== 'archived'}
+/>
+```
+
+- `isCellEditable` can only restrict. It cannot make a column without `editable: true` editable. If it throws, the cell is treated as read-only.
+- Row-grouping group rows and the ancestors tree data generates for missing path segments are never editable. Tree-data **parent rows are your own rows** and are editable like any other row.
+- Pinned rows (`pinnedRows`) are edited like any other row, with double-click or Enter (v3.0; they used to show no editor).
+- **Enter** on a cell that is not editable does what clicking its row does (`onRowClick`, click-to-select, expanding a group). See [Keyboard & Accessibility](keyboard-navigation.md).
+
 ### Persistence
 When a cell edit is committed, the `processRowUpdate` callback is triggered.
 
@@ -33,6 +54,82 @@ When a cell edit is committed, the `processRowUpdate` callback is triggered.
 />
 ```
 
+`processRowUpdate` must return the row to store (or a Promise of it). The grid stores that row under the id of the row you edited, so a server response that lacks the key field (for example the `uid` read by `getRowId={r => r.uid}`) is still applied. The row is stored as returned: the grid never adds an `id` field to it (v3.0+). Returning nothing is a mistake the grid reports through `onProcessRowUpdateError` (or `console.error` in development when no handler is set); the editor stays open.
+
+### Commit and cancel
+
+| Action | Result |
+| :--- | :--- |
+| **Enter** | Commits and closes the editor. |
+| **Tab** / **Shift+Tab** | Commits and moves to the next / previous editable cell. With no editable cell left, focus moves on out of the grid and the edit commits. Outside edit mode Tab is not captured: it leaves the grid. |
+| Moving focus away (clicking another cell or any control outside the grid) | Commits. Focus stays where you put it. |
+| The edited cell leaving the grid (scrolled out of the render window, filtered out, another page) | Commits, as if the editor had lost focus. |
+| Starting an edit on another cell | Commits the current edit first. |
+| **Escape** | Discards the pending value and closes the editor. |
+
+Clicks and double-clicks inside an open editor stay in the editor: you can place the caret, select a word or open a dropdown. They do not fire `onCellClick`, `onRowClick` or `onRowDoubleClick`, and do not change row selection. While an IME is composing (Japanese, Chinese, Korean input), **Enter** confirms the candidate and does not commit.
+
+`processRowUpdate` runs **once per commit**. Actions that overlap, such as pressing Enter and then clicking elsewhere while an async save is in flight, share that one call.
+
+With an async `processRowUpdate`, the editor stays open until the Promise settles:
+- **Resolved:** the returned row is stored and the editor closes. If the user kept typing meanwhile, the editor stays open with the newer text, which the next commit saves.
+- **Rejected:** `onProcessRowUpdateError` receives the error and the editor stays open with the pending value, so the user can fix it or press Escape.
+- **Escape while pending** closes the editor at once, but cannot recall the save: when it resolves, the returned row is still stored, because your `processRowUpdate` has already run.
+- A late result never closes an edit the user has started on another cell.
+
+### Built-in editors
+The editor follows the column `type`, and commits values of the same type the cell held.
+
+| `type` | Editor | Committed value |
+| :--- | :--- | :--- |
+| `'string'` (default) | Text input | String. |
+| `'number'` | Number input | Number, or `null` when cleared. |
+| `'boolean'` | Checkbox | Toggling commits immediately. |
+| `'singleSelect'` | `<select>` over `valueOptions` | The option's own value: `{ value: 2, label: 'Closed' }` commits the number `2`, not `'2'`. When the current value is empty or not among the options, an empty choice is shown, so any option can be picked. |
+| `'date'` | Date input | Same kind as before: a `Date` stays a `Date` (keeping its time of day), a timestamp stays a timestamp, an ISO date-time string keeps its time part. `null` when cleared. |
+
+Every editor is labelled with the column's `headerName` (or `field`) for screen readers.
+
+### Custom editors (`renderEditCell`)
+`renderEditCell` receives the usual cell params, with `value` set to the pending value, plus three callbacks:
+
+```tsx
+import type { GridColDef, GridRenderEditCellParams } from '@opencorestack/opengridx';
+
+function RatingEditor({ value, onValueChange, onCommit, onCancel }: GridRenderEditCellParams) {
+  return (
+    <input
+      type="range" min={0} max={5} autoFocus
+      value={Number(value ?? 0)}
+      onChange={e => onValueChange(Number(e.target.value))}
+      onBlur={onCommit}
+      onKeyDown={e => { if (e.key === 'Escape') onCancel(); }}
+    />
+  );
+}
+
+const columns: GridColDef[] = [
+  { field: 'rating', type: 'number', editable: true, renderEditCell: params => <RatingEditor {...params} /> },
+];
+```
+
+Enter and Escape keydowns that bubble out of a custom editor also commit and cancel. An error thrown by `renderEditCell` is contained to its cell (the cell shows `⚠`), like `renderCell`.
+
+### Computed columns (`valueGetter` + `valueSetter`)
+An editable column with a `valueGetter` edits the derived value. Give it a `valueSetter` so the commit can write the value back to the fields it comes from; otherwise the commit writes `row[field]`, which the `valueGetter` ignores, and a development warning is logged.
+
+```tsx
+{
+  field: 'fullName',
+  editable: true,
+  valueGetter: ({ row }) => `${row.firstName} ${row.lastName}`,
+  valueSetter: ({ value, row }) => {
+    const [firstName, ...rest] = String(value).split(' ');
+    return { ...row, firstName, lastName: rest.join(' ') };
+  },
+}
+```
+
 ---
 
 ## ↕️ Row Reordering
@@ -45,10 +142,9 @@ Allows users to rearrange rows by dragging a handle.
 
 ```tsx
 <DataGrid
+  rows={rows}
   rowReordering={true}
-  onRowOrderChange={(params) => {
-    const { oldIndex, targetIndex } = params;
-    // Move logic
+  onRowOrderChange={({ oldIndex, targetIndex }) => {
     const newRows = [...rows];
     const [moved] = newRows.splice(oldIndex, 1);
     newRows.splice(targetIndex, 0, moved);
@@ -57,8 +153,19 @@ Allows users to rearrange rows by dragging a handle.
 />
 ```
 
-> [!IMPORTANT]
-> Row reordering is usually disabled when sorting or filtering is active to prevent index confusion.
+### What the indices mean
+`oldIndex` and `targetIndex` are positions in **your `rows` prop** (v3.0+), so `rows[oldIndex] === params.row` and the splice above always moves the row that was dragged. This holds on every page, with pinned rows, and while the grid is sorted or filtered. (Before v3.0 they were positions in the visible page, which moved the wrong row in all of those cases.)
+
+`params.row` is your own row object, also with `getRowId`.
+
+While the grid is sorted, the new position in `rows` does not change where the row shows up: the sort decides that. Turn sorting off if the drag should visibly move the row.
+
+### Which rows can be dragged
+- Every data row you passed in `rows` can be dragged and dropped on.
+- Pinned rows (`pinnedRows`) keep their place. They show an empty handle cell, so their cells line up with the header, but cannot be dragged or dropped on.
+- Rows the grid makes itself cannot be dragged or dropped on: row-grouping group rows and the tree-data parents generated for missing path segments.
+- While pivot mode is active, row reordering is off (no handle column): pivot rows are generated, so their positions mean nothing in `rows`. It comes back when pivoting ends.
+- Only the grid's own row drags are accepted: dropping a file, a text selection or a header on a row does nothing.
 
 ---
 
@@ -73,26 +180,26 @@ Use the `disableColumnReorder` prop to control this feature globally.
 <DataGrid disableColumnReorder={true} />
 ```
 
+`disableColumnReorder` only removes the user's ways to reorder (header drag, Columns-panel reorder). A controlled `columnOrder` or `initialState.columns.columnOrder` still sets the order, so you can fix a custom order and stop users from changing it.
+
 ### Controlled Column Order
-You can manage the column order state explicitly using `columnOrder` and `onColumnOrderChange`.
+Manage the order yourself with `columnOrder` and `onColumnOrderModelChange`, which receives the whole new order after every change: a header drag, a drag in the Columns panel, and the panel's **Reset**.
 
 ```tsx
-const [colOrder, setColOrder] = useState(['id', 'name', 'status']);
+const [colOrder, setColOrder] = useState<string[]>(['id', 'name', 'status']);
 
 <DataGrid
   columnOrder={colOrder}
-  onColumnOrderChange={(params) => {
-    // params: { column: GridColDef, oldIndex: number, targetIndex: number }
-    const newOrder = [...colOrder];
-    const [moved] = newOrder.splice(params.oldIndex, 1);
-    newOrder.splice(params.targetIndex, 0, moved);
-    setColOrder(newOrder);
-  }}
+  onColumnOrderModelChange={setColOrder}
 />
 ```
 
+`onColumnOrderChange` still fires for every single move, with `{ column, oldIndex, targetIndex }`. The indices are positions in the grid's **full** column order: every current column (hidden columns and the row-grouping `__group__` column included), in its current order. Splicing your `columnOrder` with them is only right when it lists every column; prefer `onColumnOrderModelChange`. The panel's Reset does not fire `onColumnOrderChange`.
+
+Columns missing from `columnOrder` (added later, for example) are still shown, placed by their position in `columns`.
+
 ### Non-Reorderable Columns
-To prevent all columns from being reordered, use `disableColumnReorder` on the grid. For individual column control, pin the column using `pinnedColumns` at the grid level — pinned columns do not participate in drag-reorder.
+To prevent all columns from being reordered, use `disableColumnReorder` on the grid. Pinned columns (`pinnedColumns`, and the row-grouping column) keep their place: their headers cannot be dragged, and a header dropped on them does nothing. Unpin a column to move it. `pinnable: false` only stops a column from being pinned; it can still be reordered (v3.0+).
 
 ```tsx
 // Disable reordering globally
@@ -101,3 +208,5 @@ To prevent all columns from being reordered, use `disableColumnReorder` on the g
 // Keep a column fixed by pinning it
 <DataGrid pinnedColumns={{ left: ['id'] }} />
 ```
+
+Under `columnGroupingModel`, a column can only be dropped on a column of the same group.