@opencorestack/opengridx 0.1.6 → 0.1.7

package/docs/features/loading-states.md

@@ -0,0 +1,68 @@
+# ⏳ Loading States & Performance
+
+OpenGridX provides multiple ways to handle data loading, from initial shimmers to background fetching.
+
+---
+
+## 🦴 Skeleton Loading
+
+The grid features a smart skeleton loader that automatically calculates the number of columns and rows needed to fill the viewport.
+
+### Usage
+```tsx
+<DataGrid loading={true} />
+```
+
+### Features
+- **Dynamic Calculation**: Skeletons match the current column widths and configuration.
+- **Shimmer Animation**: Uses a CSS-optimized animation for a premium feel.
+- **Auto-Fill**: Fills the entire visible height if `rows` are empty.
+
+---
+
+## ♾️ Infinite Loading
+
+For large datasets, use the `paginationMode="infinite"` to load data as the user scrolls.
+
+- **Trigger**: Fired when the user scrolls near the bottom of the grid.
+- **Feedback**: Displays skeleton rows at the bottom while new data is being fetched.
+- **Guide**: See [Infinite Scroll Guide](./infinite-scroll.md) for full implementation details.
+
+---
+
+## 💤 Lazy Loading (Viewport)
+
+Unlike infinite scroll which appends data to the end, Lazy Loading fetches specific chunks based on the user's current scroll position (viewport).
+
+- **Benefit**: Best for datasets with millions of records where users might "jump" to the middle of the scrollbar.
+- **Implementation**: Managed via the `GridDataSource` and `rowCount` props.
+
+---
+
+## 🔍 Global Search (Quick Filter)
+
+Quickly filter the entire dataset across all visible columns. This is managed via the `GridToolbar`.
+
+### Basic Setup
+```tsx
+<DataGrid
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{
+    toolbar: {
+       showQuickFilter: true
+    }
+  }}
+/>
+```
+
+### Controlled Search
+You can also control the search value externally via the `filterModel`.
+
+```tsx
+<DataGrid
+  filterModel={{
+    items: [],
+    quickFilterValues: ['search term']
+  }}
+/>
+```

package/docs/features/master-detail.md

@@ -0,0 +1,46 @@
+# 📋 Master-Detail (Detail Panel)
+
+Display supplementary information for a row in an expandable panel without leaving the main grid view.
+
+---
+
+## 🛠️ Basic Implementation
+
+To enable detail panels, provided two main props: `getDetailPanelContent` and `getDetailPanelHeight`.
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  getDetailPanelContent={(params) => (
+    <div style={{ padding: '20px' }}>
+      <h3>Details for {params.row.name}</h3>
+      <p>{params.row.description}</p>
+    </div>
+  )}
+  getDetailPanelHeight={() => 'auto'} // or a fixed number
+/>
+```
+
+---
+
+## 🕹️ Controlled Expansion
+
+You can manage which rows are expanded by using the `detailPanelExpandedRowIds` and `onDetailPanelExpandedRowIdsChange` props.
+
+```tsx
+const [expandedIds, setExpandedIds] = useState(new Set());
+
+<DataGrid
+  detailPanelExpandedRowIds={expandedIds}
+  onDetailPanelExpandedRowIdsChange={setExpandedIds}
+/>
+```
+
+---
+
+## 🎨 Layout Impact
+
+- **Expansion Column**: A `+` icon is automatically added to the start of the row.
+- **Pinning**: The expansion column can be pinned using `pinExpandColumn={true}`. This ensures the expansion trigger is always visible even when scrolling horizontally.
+- **Virtualization**: The grid engine correctly accounts for variable row heights when detail panels are open.

package/docs/features/pinning.md

@@ -0,0 +1,67 @@
+# 📌 Pinning (Rows & Columns)
+
+Keep critical data visible while scrolling through large tables.
+
+---
+
+## ⬅️ Column Pinning
+
+Columns can be pinned to the left or right edges of the grid. Pinned columns remain sticky while the rest of the columns scroll horizontally.
+
+### Implementation
+```tsx
+<DataGrid
+  pinnedColumns={{
+    left: ['name', 'department'],
+    right: ['actions']
+  }}
+/>
+```
+
+### Column Configuration
+Individual columns can be marked as non-pinnable:
+```typescript
+{ field: 'id', pinnable: false }
+```
+
+---
+
+## ⬆️ Row Pinning
+
+Rows can be pinned to the top or bottom of the grid. Pinned rows remain visible while the user scrolls vertically through the grid body.
+
+### Implementation
+```tsx
+<DataGrid
+  pinnedRows={{
+    top: ['row-1', 'row-5'], // Array of Row IDs
+    bottom: ['row-summary']
+  }}
+/>
+```
+
+### Use Cases
+- **Header Summary**: Keep a "Totals" or "Averages" row at the top.
+- **Comparison**: Pin a specific row to compare it against other data.
+- **Actions footer**: Pin a specialized row for bulk actions at the bottom.
+
+---
+
+## ⚙️ API Reference
+
+### Props
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `pinnedColumns` | `GridColumnPinning` | `{ left: string[], right: string[] }` |
+| `pinnedRows` | `GridRowPinning` | `{ top: GridRowId[], bottom: GridRowId[] }` |
+| `onPinnedColumnsChange` | `(model) => void` | Callback triggered when pinning changes. |
+| `onPinnedRowsChange` | `(model) => void` | Callback triggered when row pinning changes. |
+
+---
+
+## 🎨 Styling Pinning
+Pinned elements have specific CSS shadow classes applied to indicate depth:
+- `.ogx-column--pinned-left--last`
+- `.ogx-column--pinned-right--first`
+
+These can be customized via your theme or global CSS.

package/docs/features/selection.md

@@ -0,0 +1,70 @@
+# ✅ Row Selection
+
+OpenGridX provides various ways for users to select one or multiple rows.
+
+---
+
+## 🔘 Selection Modes
+
+| Mode | Description |
+| :--- | :--- |
+| **Checkbox Selection** | Adds a column with checkboxes for bulk selection. |
+| **Row Click Selection** | Select a row by clicking anywhere on the row body. |
+| **Single Selection** | Limit the user to picking only one row at a time. |
+
+---
+
+## 🛠️ Implementation
+
+### Enable Checkbox Selection
+```tsx
+<DataGrid
+  checkboxSelection
+  pinCheckboxColumn // Optional: keeps checkbox on the left during horizontal scroll
+/>
+```
+
+### Controlled Selection
+Use the `rowSelectionModel` to control the selection state from your parent component.
+
+```tsx
+const [selection, setSelection] = useState<GridRowId[]>([]);
+
+<DataGrid
+  rowSelectionModel={selection}
+  onRowSelectionModelChange={(newSelection) => setSelection(newSelection)}
+/>
+```
+
+---
+
+## ⚙️ API Reference
+
+### Props
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `checkboxSelection` | `boolean` | `false` | Enable the checkbox column. |
+| `disableRowSelectionOnClick` | `boolean` | `false` | If true, clicking a cell won't select the row. |
+| `disableMultipleRowSelection` | `boolean` | `false` | Restricts selection to a single row. |
+| `rowSelectionModel` | `GridRowId[]` | `[]` | Controlled array of selected IDs. |
+| `isRowSelectable` | `(params) => boolean` | `undefined` | Predicate to disable selection for specific rows. |
+
+---
+
+## 🖱️ Interaction Callbacks
+
+### `onRowClick`
+Fired when a row is clicked (even if selection is disabled on click).
+```typescript
+onRowClick: (params: GridRowParams) => {
+  console.log('Row clicked:', params.id, params.row);
+}
+```
+
+### `onCellClick`
+Fired when a specific cell is clicked.
+```typescript
+onCellClick: (params: GridCellParams) => {
+  console.log('Cell clicked:', params.field, params.value);
+}
+```

package/docs/features/sorting-pagination.md

@@ -0,0 +1,66 @@
+# 🔢 Sorting & Pagination
+
+Efficiently naviagte and organize through large datasets using OpenGridX's sorting and pagination engines.
+
+---
+
+## 🔼 Column Sorting
+
+Sorting can be toggled by clicking column headers. It supports single-column and multi-column (Shift+Click) sorting.
+
+### Props
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `sortingMode` | `'client' \| 'server'` | Whether to sort locally or on the server. |
+| `sortModel` | `GridSortItem[]` | Controlled state of active sorts. |
+| `onSortModelChange` | `(model) => void` | Callback triggered when sorting changes. |
+
+### Column-Specific Config
+Disable sorting for specific columns in `GridColDef`:
+```typescript
+{ field: 'actions', sortable: false }
+```
+
+---
+
+## 📄 Pagination
+
+OpenGridX supports standard page-based pagination and infinite scrolling.
+
+### Usage
+```tsx
+<DataGrid
+  pagination
+  paginationModel={{ page: 0, pageSize: 10 }}
+  pageSizeOptions={[5, 10, 20, 50]}
+/>
+```
+
+### Server-Side Pagination
+When using `paginationMode="server"`, you must provide the `rowCount` and handle page changes in your `dataSource`.
+
+```tsx
+<DataGrid
+  pagination
+  paginationMode="server"
+  rowCount={1000} // Total rows on server
+  onPaginationModelChange={(model) => fetchNextPage(model)}
+/>
+```
+
+### Props
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `pagination` | `boolean` | `false` | Enable/disable the pagination footer. |
+| `paginationMode` | `'client' \| 'server'` | `'client'` | Location of the pagination logic. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Options for the rows-per-page selector. |
+
+---
+
+## ⚡ Infinite Scrolling
+For a more modern experience, use infinite scroll combined with virtualization.
+
+1. Set `paginationMode="infinite"`.
+2. Implement `onRowsScrollEnd` or use the `dataSource.getRows` method to fetch data as the user scrolls.
+
+📖 **[Full Infinite Scroll Guide](docs/features/infinite-scroll.md)**

package/docs/features/state-persistence.md

@@ -0,0 +1,67 @@
+# 💾 State Persistence
+
+Save and restore the grid's configuration (sorting, filtering, column order, etc.) to provide a consistent experience for returning users.
+
+---
+
+## 🏗️ The `initialState` Prop
+
+You can pre-configure the grid status on mount using the `initialState` prop.
+
+```tsx
+<DataGrid
+  initialState={{
+    sorting: {
+      sortModel: [{ field: 'name', sort: 'asc' }]
+    }
+  }}
+/>
+```
+
+---
+
+## ⚓ The `useGridStateStorage` Hook
+
+OpenGridX provides a built-in hook to simplify `localStorage` persistence.
+
+```tsx
+import { DataGrid, useGridStateStorage } from '@opencorestack/opengridx';
+
+export default function MyGrid() {
+  const { initialState, onStateChange } = useGridStateStorage('my-app-storage-key');
+
+  return (
+    <DataGrid
+      initialState={initialState}
+      onStateChange={onStateChange}
+      // ...
+    />
+  );
+}
+```
+
+---
+
+## 📡 Tracking Changes
+
+Use the `onStateChange` callback to listen for any modifications to the grid state and save them to `localStorage` or a database.
+
+```tsx
+<DataGrid
+  onStateChange={(state) => {
+    localStorage.setItem('grid-state', JSON.stringify(state));
+  }}
+/>
+```
+
+---
+
+## 🧩 Supported State Objects
+
+The following features support state persistence:
+- **Sorting**: `sortModel`
+- **Filtering**: `filterModel`
+- **Pagination**: `paginationModel`
+- **Columns**: `columnVisibilityModel`, `columnOrder`, `pinnedColumns`, `columnWidths`
+- **Selection**: `rowSelectionModel`
+- **Grouping**: `rowGroupingModel`

package/docs/features/tree-data-grouping.md

@@ -0,0 +1,67 @@
+# 🌳 Tree Data & Row Grouping
+
+Display complex, hierarchical data structures with ease.
+
+---
+
+## 📂 Row Grouping
+
+Row grouping allows you to categorize rows based on common column values.
+
+### Usage
+```tsx
+<DataGrid
+  rows={rows}
+  rowGroupingModel={['department', 'role']}
+/>
+```
+
+### Features
+- **Multi-Level Groups**: Nest data as deeply as needed.
+- **Aggregation Integration**: Summarize values automatically for each group level.
+- **Expansion Control**: Control which groups are expanded by default.
+
+---
+
+## 🌿 Tree Data
+
+Tree data is used for data that has a natural parent-child relationship (e.g., an organizational chart or file system).
+
+### Implementation
+1. Enable `treeData={true}`.
+2. Provide a `getTreeDataPath` function to define the hierarchy.
+
+```tsx
+<DataGrid
+  treeData
+  getTreeDataPath={(row) => row.hierarchyPath} // e.g. ['CEO', 'VP Engineering', 'Manager']
+/>
+```
+
+---
+
+## ⚙️ API Reference
+
+### Props
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `rowGroupingModel` | `string[]` | `[]` | Fields to group by (in order). |
+| `treeData` | `boolean` | `false` | Enable tree data mode. |
+| `getTreeDataPath` | `(row) => string[]` | `undefined` | Function to get the path for a row. |
+| `defaultGroupingExpansionDepth` | `number` | `0` | How many levels to expand on load. |
+| `groupingColDef` | `GridColDef` | `undefined` | Custom configuration for the generated group column. |
+
+---
+
+## 🎨 Customizing the Group Column
+By default, OpenGridX creates a `__group__` column. You can customize its appearance:
+
+```tsx
+<DataGrid
+  groupingColDef={{
+    headerName: 'Hierarchy',
+    width: 300,
+    renderCell: (params) => { /* custom renderer */ }
+  }}
+/>
+```

package/docs/features/virtualization.md

@@ -0,0 +1,188 @@
+# Virtualization
+
+The DataGrid uses **row and column virtualization** to efficiently render large datasets by only rendering the rows and columns that are currently visible in the viewport, plus a small buffer (overscan) for smooth scrolling.
+
+## Overview
+
+Virtualization is a technique that dramatically improves performance when working with large datasets. Instead of rendering all rows in the DOM (which would be slow and memory-intensive), the grid only renders:
+
+1. **Visible rows** - Rows currently in the viewport
+2. **Overscan rows** - A buffer of rows above and below the viewport for smooth scrolling
+3. **Pinned rows** - Rows that are always visible (top/bottom)
+
+## How It Works
+
+### Row Virtualization
+
+The grid calculates which rows are visible based on:
+- Current scroll position
+- Viewport height
+- Row height (fixed or variable)
+- Overscan buffer (default: 5 rows)
+
+```tsx
+// Example: 1000 rows, but only ~15 rendered at a time
+<DataGrid
+  rows={thousandRows}
+  columns={columns}
+  style={{ height: 600 }}
+/>
+```
+
+**Performance characteristics:**
+- ✅ Renders ~15-25 rows regardless of total dataset size
+- ✅ Constant memory usage
+- ✅ Smooth 60fps scrolling
+- ✅ Supports millions of rows
+
+### Column Virtualization
+
+Currently, the DataGrid renders all columns. Column virtualization (rendering only visible columns) is planned for future releases.
+
+## Configuration
+
+### Row Height
+
+The grid supports both fixed and variable row heights:
+
+```tsx
+// Fixed row height (default: 52px)
+<DataGrid
+  rows={rows}
+  columns={columns}
+  rowHeight={40}
+/>
+```
+
+### Auto Height
+
+Disable virtualization for small datasets:
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  autoHeight
+/>
+```
+
+⚠️ **Warning:** `autoHeight` disables row virtualization and renders all rows. Only use for small datasets (< 100 rows).
+
+## Performance Optimization
+
+### Overscan Buffer
+
+The overscan buffer determines how many extra rows are rendered outside the viewport. A larger buffer provides smoother scrolling but uses more memory.
+
+**Current implementation:**
+- Default overscan: **5 rows** (above and below viewport)
+- Total rendered rows: ~(viewport rows + 10)
+
+**Trade-offs:**
+- **Smaller overscan (1-3)**: Less memory, potential flickering during fast scrolling
+- **Larger overscan (5-8)**: More memory, smoother fast scrolling
+- **Very large overscan (10+)**: Diminishing returns, wasted rendering
+
+### Scroll Performance
+
+For optimal scroll performance:
+
+1. **Use fixed row heights** when possible
+2. **Avoid complex cell renderers** - Keep `renderCell` functions lightweight
+3. **Memoize custom components** - Use `React.memo` for custom cell components
+4. **Minimize re-renders** - Use stable column definitions
+
+```tsx
+// ✅ Good: Memoized columns
+const columns = useMemo(() => [
+  { field: 'id', headerName: 'ID', width: 70 },
+  { field: 'name', headerName: 'Name', width: 200 }
+], []);
+
+// ❌ Bad: New column array on every render
+const columns = [
+  { field: 'id', headerName: 'ID', width: 70 },
+  { field: 'name', headerName: 'Name', width: 200 }
+];
+```
+
+## Detail Panel Considerations
+
+When using detail panels, row heights become variable. The grid automatically:
+- Calculates cumulative heights for each row
+- Adjusts scroll calculations for expanded panels
+- Maintains smooth scrolling
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  getDetailPanelContent={({ row }) => <DetailPanel row={row} />}
+  getDetailPanelHeight={() => 200}
+/>
+```
+
+## Virtualization with Grouping/Tree Data
+
+Row grouping and tree data work seamlessly with virtualization:
+
+```tsx
+// Tree data with virtualization
+<DataGrid
+  rows={rows}
+  columns={columns}
+  treeData
+  getTreeDataPath={(row) => row.path}
+  defaultGroupingExpansionDepth={-1} // Expand all
+/>
+```
+
+**Note:** When groups are collapsed, only visible rows are rendered. Expanding a group dynamically adds rows to the render list.
+
+## Debugging Virtualization
+
+To see which rows are being rendered:
+
+```tsx
+// Add this to your column definition
+{
+  field: 'debug',
+  headerName: 'Debug',
+  renderCell: (params) => {
+    console.log('Rendering row:', params.row.id);
+    return params.row.id;
+  }
+}
+```
+
+You should see console logs only for visible rows + overscan buffer.
+
+## Known Limitations
+
+1. **Column virtualization** - Not yet implemented (all columns are rendered)
+2. **Dynamic row heights** - Requires full dataset scan for accurate scroll calculations
+3. **Horizontal scrolling** - May show brief flicker with very wide grids
+
+## Future Improvements
+
+- [ ] Column virtualization for grids with 50+ columns
+- [ ] Adaptive overscan based on scroll velocity
+- [ ] Virtual scrollbar for extremely large datasets (millions of rows)
+- [ ] Intersection Observer API for better scroll detection
+
+## Comparison with MUI X DataGrid
+
+| Feature | Aui DataGrid | MUI X DataGrid |
+|---------|--------------|----------------|
+| Row virtualization | ✅ Yes | ✅ Yes |
+| Column virtualization | ❌ Planned | ✅ Yes (Pro) |
+| Variable row heights | ✅ Yes | ✅ Yes |
+| Overscan buffer | 5 rows | 3-8 rows (adaptive) |
+| Max recommended rows | 100,000+ | 100,000+ |
+
+## Related Documentation
+
+- [Performance Best Practices](../performance.md)
+- [Row Grouping](./tree-data-grouping.md)
+- [Tree Data](./tree-data-grouping.md)
+- [Detail Panel](./master-detail.md)