@opencorestack/opengridx 0.1.5 → 0.1.7

package/docs/features/custom-pagination.md

@@ -0,0 +1,143 @@
+# Custom Pagination with Ant Design
+
+This guide shows how to use Ant Design (or any other UI library) components with the DataGrid.
+
+## Using Ant Design Select for Page Size
+
+```tsx
+import { Select } from 'antd';
+import { DataGrid } from '@opencorestack/opengridx';
+
+function AntdPaginationComponent(props) {
+    const {
+        page,
+        pageSize,
+        rowCount,
+        pageSizeOptions,
+        onPageChange,
+        onPageSizeChange
+    } = props;
+
+    const pageCount = Math.max(1, Math.ceil(rowCount / pageSize));
+    const currentPage = Math.min(page, pageCount - 1);
+    const firstRowIndex = currentPage * pageSize;
+    const lastRowIndex = Math.min(firstRowIndex + pageSize, rowCount);
+
+    return (
+        <div style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'flex-end',
+            gap: '16px',
+            padding: '12px 16px',
+            borderTop: '1px solid #f0f0f0'
+        }}>
+            {/* Ant Design Select for page size */}
+            <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+                <span>Rows per page:</span>
+                <Select
+                    value={pageSize}
+                    onChange={onPageSizeChange}
+                    options={pageSizeOptions.map(size => ({
+                        value: size,
+                        label: size
+                    }))}
+                    style={{ width: 80 }}
+                />
+            </div>
+
+            {/* Row count */}
+            <span>{firstRowIndex + 1}–{lastRowIndex} of {rowCount}</span>
+
+            {/* Ant Design Pagination */}
+            <Pagination
+                current={currentPage + 1}
+                total={rowCount}
+                pageSize={pageSize}
+                onChange={(page) => onPageChange(page - 1)}
+                showSizeChanger={false}
+                simple
+            />
+        </div>
+    );
+}
+
+// Usage in your app
+function MyApp() {
+    return (
+        <DataGrid
+            rows={rows}
+            columns={columns}
+            pagination
+            slots={{
+                pagination: AntdPaginationComponent
+            }}
+            slotProps={{
+                pagination: {
+                    // Any custom props for your component
+                }
+            }}
+        />
+    );
+}
+```
+
+## Using MUI Select
+
+```tsx
+import { Select, MenuItem } from '@mui/material';
+
+function MuiPaginationComponent(props) {
+    const { pageSize, pageSizeOptions, onPageSizeChange } = props;
+
+    return (
+        <div>
+            <Select
+                value={pageSize}
+                onChange={(e) => onPageSizeChange(e.target.value)}
+            >
+                {pageSizeOptions.map(size => (
+                    <MenuItem key={size} value={size}>
+                        {size}
+                    </MenuItem>
+                ))}
+            </Select>
+        </div>
+    );
+}
+```
+
+## Available Props
+
+Your custom pagination component will receive these props:
+
+- `page`: Current page index (0-based)
+- `pageSize`: Current page size
+- `rowCount`: Total number of rows
+- `pageSizeOptions`: Array of available page sizes
+- `onPageChange(newPage: number)`: Callback to change page
+- `onPageSizeChange(newPageSize: number)`: Callback to change page size
+- Any additional props from `slotProps.pagination`
+
+## Other Customizable Slots
+
+```tsx
+<DataGrid
+    slots={{
+        pagination: CustomPaginationComponent,
+        noRowsOverlay: CustomNoRowsComponent,
+        loadingOverlay: CustomLoadingComponent,
+        footer: CustomFooterComponent
+    }}
+    slotProps={{
+        pagination: { /* custom props */ },
+        noRowsOverlay: { /* custom props */ },
+        loadingOverlay: { /* custom props */ },
+        footer: { /* custom props */ }
+    }}
+/>
+```
+
+## Complete Example
+
+See `demo/examples/CustomPagination.tsx` for a complete working example.

package/docs/features/data-source.md

@@ -0,0 +1,72 @@
+# 🌐 Server-Side Data Source
+
+Handle millions of rows by connecting OpenGridX directly to your backend API.
+
+---
+
+## 📑 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.
+
+### Implementation
+```tsx
+const myDataSource: GridDataSource = {
+  getRows: async (params) => {
+    const { startRow, endRow, sortModel, filterModel } = params;
+    
+    const response = await fetch('/api/data', {
+      method: 'POST',
+      body: JSON.stringify({ startRow, endRow, sortModel, filterModel })
+    });
+    
+    const data = await response.json();
+    
+    return {
+      rows: data.items,
+      rowCount: data.totalCount // Required for stable pagination
+    };
+  }
+};
+
+<DataGrid dataSource={myDataSource} />
+```
+
+---
+
+## ⚙️ Request Parameters (`GridGetRowsParams`)
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `startRow` | `number` | The starting index of the requested range. |
+| `endRow` | `number` | The ending index (exclusive). |
+| `sortModel` | `GridSortItem[]` | Current sorting configuration. |
+| `filterModel` | `GridFilterModel` | Current filtering configuration. |
+| `groupKeys` | `string[]` | Active expansion path (used for server-side tree data). |
+
+---
+
+## 🔄 Modes of Operation
+
+### 1. Server-Side Pagination
+Set `paginationMode="server"`. The grid will request fresh data every time the page changes.
+
+### 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.
+
+### 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.
+
+---
+
+## 🛠️ 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.
+
+```typescript
+getRows: async () => {
+  try {
+    return await apiCall();
+  } catch (err) {
+    throw new Error("Failed to connect to database");
+  }
+}
+```

package/docs/features/editing-reordering.md

@@ -0,0 +1,99 @@
+# ✏️ Editing & ↕️ Reordering
+
+Capture user input directly in the grid and rearrange data with intuitive drag-and-drop interactions.
+
+---
+
+## 🏗️ Cell Editing
+
+OpenGridX supports inline cell editing. For a column to be editable, you must set `editable: true` in its definition.
+
+### Basic Setup
+```tsx
+const columns = [
+  { field: 'name', editable: true },
+  { field: 'role', editable: true, type: 'singleSelect', valueOptions: ['Admin', 'Editor'] }
+];
+```
+
+### Persistence
+When a cell edit is committed, the `processRowUpdate` callback is triggered.
+
+```tsx
+<DataGrid
+  processRowUpdate={(newRow, oldRow) => {
+    // Save to your database/state here
+    const updatedRows = rows.map(r => r.id === newRow.id ? newRow : r);
+    setRows(updatedRows);
+    return newRow; // Return the new row to confirm saving
+  }}
+  onProcessRowUpdateError={(error) => {
+    console.error('Update failed:', error);
+  }}
+/>
+```
+
+---
+
+## ↕️ Row Reordering
+
+Allows users to rearrange rows by dragging a handle.
+
+### Enable
+1. Set `rowReordering={true}` on the grid.
+2. Handle the `onRowOrderChange` callback.
+
+```tsx
+<DataGrid
+  rowReordering={true}
+  onRowOrderChange={(params) => {
+    const { oldIndex, targetIndex } = params;
+    // Move logic
+    const newRows = [...rows];
+    const [moved] = newRows.splice(oldIndex, 1);
+    newRows.splice(targetIndex, 0, moved);
+    setRows(newRows);
+  }}
+/>
+```
+
+> [!IMPORTANT]
+> Row reordering is usually disabled when sorting or filtering is active to prevent index confusion.
+
+---
+
+## ↔️ Column Reordering
+
+Users can drag column headers to change their horizontal order. This is enabled by default.
+
+### Enable / Disable
+Use the `disableColumnReorder` prop to control this feature globally.
+
+```tsx
+<DataGrid disableColumnReorder={true} />
+```
+
+### Controlled Column Order
+You can manage the column order state explicitly using `columnOrder` and `onColumnOrderChange`.
+
+```tsx
+const [colOrder, setColOrder] = useState(['id', 'name', 'status']);
+
+<DataGrid
+  columnOrder={colOrder}
+  onColumnOrderChange={(params) => {
+    // params.newOrder is the updated array of field strings
+    setColOrder(params.newOrder);
+  }}
+/>
+```
+
+### Non-Reorderable Columns
+To prevent a specific column from being moved, set `reorderable: false` in its definition.
+
+```tsx
+const columns = [
+  { field: 'id', reorderable: false }, // Stay pinned at start
+  { field: 'name' }
+];
+```