@opencorestack/opengridx 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -5,6 +5,22 @@
 
 ---
 
+## [1.0.2] — July 30, 2026 📚
+
+### Fixed
+- **`GridColDef` documentation**: Added all previously undocumented column properties — `flex`, `minWidth`, `maxWidth`, `align`, `headerAlign`, `description`, `editable`, `renderHeader`, `renderEditCell`, `cellClassName`, `headerClassName`, `disableColumnMenu`, `groupable`, `aggregable`, `availableAggregationFunctions`, `valueOptions` (for `singleSelect`), `colSpan`, `rowSpan`. Both `README.md` and `docs/API_REFERENCE.md` now carry the complete table.
+- **Hooks documentation**: Expanded the stubs in `docs/API_REFERENCE.md` into full reference entries. `usePivot` (was entirely missing), `useGridStateStorage` (was one sentence — now has a full options + return table and code example), `useAggregation` (now has params/return tables and built-in function list), `useGridApiRef` (corrected description and added usage example).
+
+---
+
+## [1.0.1] — July 30, 2026 📚
+
+### Fixed
+- **Bundled documentation accuracy**: All doc files shipped inside the npm package (`docs/`) have been corrected to match the actual v1.0.0 API. Key fixes: removed non-existent `pageSize` standalone prop (correct API is `paginationModel` + `pageSizeOptions`), fixed `height` type to `number | string`, corrected `onColumnOrderChange` params shape, removed non-existent `isRowSelectable` and `reorderable` props, fixed `GridFilterModel.items` type, added missing `GridApi` methods (`getFilterModel`, `getAllColumns`, `setPageSize`, `getAggregationResult`, `getAggregationModel`, `copySelectedRows`), and corrected `GridInitialState` persisted state fields. AI agents (Cursor, Copilot, Windsurf) reading bundled docs will now generate accurate code.
+- **README API reference**: Same prop and type corrections applied — complete `apiRef` method list, new prop tables for Events, Columns, Pinning, Inline Editing, Row Reordering, and updated comparison table.
+
+---
+
 ## [1.0.0] — July 30, 2026 🚀
 
 First stable public release. All 32 demo pages ship with a live source viewer. npm publish workflow is live.

package/README.md

@@ -40,14 +40,14 @@ const columns: GridColDef[] = [
   { field: 'name',       headerName: 'Name',        width: 180 },
   { field: 'role',       headerName: 'Role',        width: 150 },
   { field: 'salary',     headerName: 'Salary',      width: 120, type: 'number',
-    valueFormatter: ({ value }) => `$${value.toLocaleString()}` },
+    valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}` },
   { field: 'department', headerName: 'Department',  width: 160 },
 ];
 
 const rows = [
-  { id: 1, name: 'Jon Snow',       role: 'Engineer',  salary: 95000,  department: 'Defense' },
-  { id: 2, name: 'Cersei Lannister', role: 'Manager', salary: 140000, department: 'Management' },
-  { id: 3, name: 'Arya Stark',     role: 'Analyst',   salary: 65000,  department: 'Special Ops' },
+  { id: 1, name: 'Jon Snow',         role: 'Engineer',  salary: 95000,  department: 'Defense' },
+  { id: 2, name: 'Cersei Lannister', role: 'Manager',   salary: 140000, department: 'Management' },
+  { id: 3, name: 'Arya Stark',       role: 'Analyst',   salary: 65000,  department: 'Special Ops' },
 ];
 
 export default function App() {
@@ -77,18 +77,23 @@ export default function App() {
 - **Clipboard**: `Ctrl+C` / `Cmd+C` copies selected rows as TSV for Excel/Sheets.
 - **Accessibility**: WCAG 2.1 AA — full ARIA roles and keyboard navigation.
 - **Theming**: CSS variable API with 5 built-in themes + custom theme support.
+- **Column & Row Reordering**: Drag-and-drop column reordering and row reordering.
+- **Inline Cell Editing**: Full inline editing with `processRowUpdate` validation.
+- **State Persistence**: Save and restore grid state (sort, filter, columns) via `useGridStateStorage`.
 - **AI-Native Integration**: Shipped with raw `lib/` source and `docs/` inside the npm package, allowing AI agents (Cursor, Copilot, Windsurf) to flawlessly implement features by "seeing" the internal logic.
 
 ---
 
 ## 🤖 AI-Powered Implementation
 
-OpenGridX is built for the era of AI-native development. When you install `@opencorestack/opengridx`, we include the full raw source code and markdown documentation in your `node_modules`. 
+OpenGridX is built for the era of AI-native development. When you install `@opencorestack/opengridx`, we include the full raw source code and markdown documentation in your `node_modules`.
 
 This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agents can read the actual implementation patterns and docs to accurately help you build complex features like server-side tree data or pivot tables without guessing.
 
 > **Tip for Cursor/Copilot users:** If your AI is struggling, tell it to "Read the docs and source in `./node_modules/@opencorestack/opengridx/docs`" for instant context.
 
+---
+
 ## 📐 API Reference
 
 ### Core Props
@@ -97,14 +102,57 @@ This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agent
 | :--- | :--- | :--- | :--- |
 | `rows` | `GridRowModel[]` | — | **Required.** Array of data rows. |
 | `columns` | `GridColDef[]` | — | **Required.** Column definitions. |
-| `height` | `number` | `500` | Grid height in pixels. |
+| `height` | `number \| string` | `500` | Grid height in pixels or CSS string (e.g. `'100%'`). |
+| `autoHeight` | `boolean` | `false` | Expands grid height to fit all rows. |
 | `loading` | `boolean` | `false` | Shows skeleton loader when `true`. |
+| `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density. |
 | `checkboxSelection` | `boolean` | `false` | Enables checkbox column for row selection. |
 | `pagination` | `boolean` | `false` | Enables client-side pagination. |
-| `pageSize` | `number` | `25` | Rows per page. |
+| `paginationModel` | `{ page: number; pageSize: number }` | — | Controlled pagination state. |
+| `onPaginationModelChange` | `(model) => void` | — | Fires on page or page size change. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Available page size options. |
 | `getRowId` | `(row) => GridRowId` | `row.id` | Custom row ID accessor. |
 | `rowHeight` | `number` | `52` | Row height in pixels. |
 | `headerHeight` | `number` | `56` | Header height in pixels. |
+| `noRowsLabel` | `string` | — | Custom empty-state message. |
+| `className` | `string` | — | Custom CSS class on the grid container. |
+| `style` | `React.CSSProperties` | — | Custom inline styles on the grid container. |
+
+### Column Definitions (`GridColDef`)
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `field` | `string` | — | **Required.** Must match the row object key. |
+| `headerName` | `string` | — | Header label text. |
+| `description` | `string` | — | Tooltip on header hover. |
+| `width` | `number \| string` | `100` | Fixed width in px. |
+| `flex` | `number` | — | Flex-grow weight — fills remaining space. Cannot be combined with `width`. |
+| `minWidth` | `number` | — | Minimum width in px, enforced during resize. |
+| `maxWidth` | `number` | — | Maximum width in px, enforced during resize. |
+| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Cell content alignment. |
+| `headerAlign` | `'left' \| 'center' \| 'right'` | `'left'` | Header content alignment. |
+| `type` | `'string' \| 'number' \| 'date' \| 'boolean' \| 'singleSelect' \| 'image'` | `'string'` | Drives filter operators and default formatting. |
+| `valueOptions` | `Array<string \| number \| { value, label }>` | — | Options list for `type: 'singleSelect'`. |
+| `editable` | `boolean` | `false` | Enables inline cell editing. Pair with `processRowUpdate`. |
+| `valueGetter` | `(params) => unknown` | — | Derive a computed cell value from the row. |
+| `valueFormatter` | `(params) => string` | — | Format the display string (does not affect edit or sort). |
+| `renderCell` | `(params) => ReactNode` | — | Fully custom cell renderer. |
+| `renderHeader` | `(params) => ReactNode` | — | Custom header cell renderer. |
+| `renderEditCell` | `(params) => ReactNode` | — | Custom editor rendered in edit mode. |
+| `cellClassName` | `string \| ((params) => string)` | — | CSS class on every cell; use a function for conditional per-row styling. |
+| `headerClassName` | `string` | — | CSS class on the header cell. |
+| `colSpan` | `number \| ((params) => number)` | — | Merge cells horizontally. |
+| `rowSpan` | `number \| ((params) => number)` | — | Merge cells vertically. |
+| `sortable` | `boolean` | `true` | Enable/disable column sorting. |
+| `filterable` | `boolean` | `true` | Enable/disable column filtering. |
+| `resizable` | `boolean` | `true` | Allow drag-resize. |
+| `hideable` | `boolean` | `true` | Allow hiding via the column panel. |
+| `pinnable` | `boolean` | `true` | Allow pinning via the UI. |
+| `disableColumnMenu` | `boolean` | `false` | Hide the column header context menu. |
+| `exportable` | `boolean` | `true` | Set to `false` to exclude from all exports. |
+| `groupable` | `boolean` | `true` | Allow as a row grouping dimension. |
+| `aggregable` | `boolean` | `true` | Allow aggregation on this column. |
+| `availableAggregationFunctions` | `string[]` | all | Restrict which aggregation functions are offered. |
 
 ### Selection
 
@@ -113,17 +161,37 @@ This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agent
 | `rowSelectionModel` | `GridRowId[]` | Controlled selected row IDs. |
 | `onRowSelectionModelChange` | `(model: GridRowId[]) => void` | Fires on selection change. |
 | `disableRowSelectionOnClick` | `boolean` | Prevent row click from toggling selection. |
+| `disableMultipleRowSelection` | `boolean` | Restrict to single-row selection. |
+| `pinCheckboxColumn` | `boolean` | Keeps the checkbox column visible during horizontal scroll. |
 
 ### Sorting & Filtering
 
 | Prop | Type | Description |
 | :--- | :--- | :--- |
 | `sortModel` | `GridSortItem[]` | Controlled sort model. |
-| `onSortModelChange` | `(model) => void` | Fires on sort change. |
+| `onSortModelChange` | `(model: GridSortItem[]) => void` | Fires on sort change. |
 | `filterModel` | `GridFilterModel` | Controlled filter model. |
-| `onFilterModelChange` | `(model) => void` | Fires on filter change. |
+| `onFilterModelChange` | `(model: GridFilterModel) => void` | Fires on filter change. |
 | `disableColumnFilter` | `boolean` | Disables column-level filtering. |
 
+### Columns
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `columnVisibilityModel` | `GridColumnVisibilityModel` | Controlled column visibility. |
+| `onColumnVisibilityModelChange` | `(model) => void` | Fires when column visibility changes. |
+| `columnOrder` | `string[]` | Controlled column field order. |
+| `onColumnOrderChange` | `(params) => void` | Fires when columns are reordered. |
+| `disableColumnReorder` | `boolean` | Disables drag-and-drop column reordering. |
+
+### Events
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `onRowClick` | `(params: GridRowParams) => void` | Fires when a row is clicked. |
+| `onCellClick` | `(params: GridCellParams) => void` | Fires when a cell is clicked. |
+| `onRowsScrollEnd` | `(params: GridRowScrollEndParams) => void` | Fires when scrolling reaches the bottom. |
+
 ### Server-Side
 
 | Prop | Type | Description |
@@ -134,11 +202,60 @@ This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agent
 | `dataSource` | `GridDataSource` | Server-side data adapter. |
 | `rowCount` | `number` | Total rows for server-side pagination. |
 
+### Pinning
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `pinnedColumns` | `GridColumnPinning` | Pin columns to `left` or `right`. |
+| `onPinnedColumnsChange` | `(model) => void` | Fires when column pinning changes. |
+| `pinnedRows` | `GridRowPinning` | Pin rows to `top` or `bottom`. |
+| `onPinnedRowsChange` | `(model) => void` | Fires when row pinning changes. |
+
+### Inline Editing
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `isCellEditable` | `(params: GridCellParams) => boolean` | Per-cell editability predicate. |
+| `processRowUpdate` | `(newRow, oldRow) => R \| Promise<R>` | Handles row save; supports async validation. |
+| `onProcessRowUpdateError` | `(error: unknown) => void` | Fires if `processRowUpdate` throws. |
+
+### Row Reordering
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `rowReordering` | `boolean` | Enables drag-and-drop row reordering. |
+| `onRowOrderChange` | `(params) => void` | Fires when rows are reordered. |
+
+### Advanced Features
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `treeData` | `boolean` | Enables hierarchical tree data display. |
+| `getTreeDataPath` | `(row) => string[]` | Returns the path array for each row in tree mode. |
+| `groupingColDef` | `GridColDef` | Overrides the auto-generated grouping column. |
+| `defaultGroupingExpansionDepth` | `number` | Initial expansion depth for tree data. |
+| `rowGroupingModel` | `GridRowGroupingModel` | Controlled row grouping state. |
+| `onRowGroupingModelChange` | `(model) => void` | Fires when grouping changes. |
+| `aggregationModel` | `GridAggregationModel` | Controlled aggregation state (e.g. `{ salary: 'sum' }`). |
+| `onAggregationModelChange` | `(model) => void` | Fires when aggregation changes. |
+| `pivotMode` | `boolean` | Switches the grid to multidimensional pivot mode. |
+| `pivotModel` | `GridPivotModel` | Controlled pivot configuration (rows, columns, values). |
+| `onPivotModelChange` | `(model) => void` | Fires when pivot model changes. |
+
+### Master-Detail
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `getDetailPanelContent` | `(params) => ReactNode` | Renders the expandable detail panel. |
+| `getDetailPanelHeight` | `(params) => number \| 'auto'` | Controls detail panel height. |
+| `detailPanelExpandedRowIds` | `Set<GridRowId>` | Controlled expanded rows. |
+| `onDetailPanelExpandedRowIdsChange` | `(ids) => void` | Fires when expanded rows change. |
+
 ### Customization
 
 | Prop | Type | Description |
 | :--- | :--- | :--- |
-| `slots` | `GridSlots` | Replace built-in components (toolbar, pagination, overlays). |
+| `slots` | `GridSlots` | Replace built-in components (toolbar, pagination, overlays, footer). |
 | `slotProps` | `GridSlotProps` | Pass custom props to slot components. |
 | `getRowClassName` | `(params) => string` | Add custom CSS class to rows. |
 | `getCellClassName` | `(params) => string` | Add custom CSS class to cells. |
@@ -150,14 +267,42 @@ This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agent
 const apiRef = useGridApiRef();
 <DataGrid apiRef={apiRef} ... />
 
-// Usage
+// Rows
+apiRef.current.getRow(id)              // → GridRowModel | null
+apiRef.current.getAllRows()            // → GridRowModel[]
+apiRef.current.getVisibleRows()        // → GridRowModel[] (post-filter/sort)
+
+// Columns
+apiRef.current.getColumn(field)        // → GridColDef | null
+apiRef.current.getAllColumns()         // → GridColDef[]
+apiRef.current.getVisibleColumns()     // → GridColDef[]
+
+// Selection
+apiRef.current.selectRow(id, true)
+apiRef.current.selectRows([id1, id2], true)
 apiRef.current.getSelectedRows()       // → GridRowId[]
-apiRef.current.copySelectedRows()      // → Promise<void>
-apiRef.current.selectRow(id, true)     // select a row
-apiRef.current.setFilterModel(model)   // programmatic filter
+
+// Sorting
 apiRef.current.sortColumn('name', 'asc')
+apiRef.current.getSortModel()          // → GridSortItem[]
+
+// Filtering
+apiRef.current.setFilterModel(model)
+apiRef.current.getFilterModel()        // → GridFilterModel
+
+// Pagination
 apiRef.current.setPage(2)
-apiRef.current.getVisibleRows()        // → GridRowModel[]
+apiRef.current.setPageSize(50)
+
+// Scroll
+apiRef.current.scrollToIndexes({ rowIndex: 100, colIndex: 3 })
+
+// Clipboard
+apiRef.current.copySelectedRows()      // → Promise<void>
+
+// Aggregation
+apiRef.current.getAggregationResult()  // → Record<string, unknown> | null
+apiRef.current.getAggregationModel()   // → GridAggregationModel | null
 ```
 
 ---
@@ -186,6 +331,20 @@ Replace any built-in component with your own:
 />
 ```
 
+### Built-in Toolbar
+
+```tsx
+import { DataGrid, GridToolbar } from '@opencorestack/opengridx';
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  slots={{ toolbar: GridToolbar }}
+/>
+```
+
+`GridToolbar` provides global search, column visibility panel, filter panel, and export controls out of the box.
+
 ### Export Functionality
 
 OpenGridX has **two tiers of Excel export**:
@@ -214,6 +373,21 @@ printGrid(rows, columns, 'Report Title');
 > npm install exceljs
 > ```
 
+### State Persistence
+
+```tsx
+import { useGridStateStorage } from '@opencorestack/opengridx';
+
+const { initialState, onStateChange } = useGridStateStorage('my-grid-key');
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  initialState={initialState}
+  onStateChange={onStateChange}
+/>
+```
+
 ### Theming
 
 ```tsx
@@ -232,11 +406,11 @@ Built-in themes: `darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compac
 
 | Artifact | Minified | Gzipped | Notes |
 | :--- | :--- | :--- | :--- |
-| **Core ES Module** (`opengridx.es.js`) | 220 KB | **52 KB** | Use this — tree-shakeable |
-| **Core UMD** (`opengridx.umd.js`) | 146 KB | **44 KB** | CommonJS / CDN compat |
-| **Styles** (`opengridx.css`) | 57 KB | **9 KB** | Auto-included |
+| **Core ES Module** (`opengridx.es.js`) | 242 KB | **58 KB** | Use this — tree-shakeable |
+| **Core UMD** (`opengridx.umd.js`) | 164 KB | **48 KB** | CommonJS / CDN compat |
+| **Styles** (`opengridx.css`) | 62 KB | **10 KB** | Auto-included |
 | **ExcelJS** (optional peer dep) | — | — | `npm install exceljs` |
-| **npm package download** | — | **400 KB** | Total compressed tarball |
+| **npm package download** | — | **613 KB** | Total compressed tarball |
 
 - **Tree-shaking Ready**: ES Module build — bundlers (Vite, Webpack) only include what you use.
 - **Zero UI Dependencies**: No MUI, Ant Design, or Radix. Pure React + vanilla CSS.
@@ -252,6 +426,8 @@ Full documentation at 👉 **[opencorestack.github.io/OpenGridX](https://opencor
 ### 🏛️ Components
 - **[DataGrid](docs/components/datagrid.md)** — Main component props and slots
 - **[Toolbar & Pagination](docs/components/toolbar.md)** — Supplemental UI components
+- **[Filter Panel](docs/components/filter-panel.md)** — Advanced filter panel component
+- **[Column Visibility](docs/components/column-visibility.md)** — Column show/hide panel
 
 ### 🚀 Features
 - **[Virtualization](docs/features/virtualization.md)** — 60fps rendering for 100k+ rows
@@ -264,6 +440,7 @@ Full documentation at 👉 **[opencorestack.github.io/OpenGridX](https://opencor
 - **[Infinite Scroll](docs/features/infinite-scroll.md)** — Seamless lazy-loading
 - **[Export Guide](docs/features/export-guide.md)** — Excel, CSV, and Print
 - **[Data Source](docs/features/data-source.md)** — Server-side integration
+- **[Loading States](docs/features/loading-states.md)** — Skeleton and shimmer overlays
 
 ### 📊 Advanced Data
 - **[Aggregation & Pivot](docs/features/aggregation-pivot.md)** — Summary totals
@@ -292,6 +469,8 @@ Most React grids gatekeep essential features like **Row Grouping**, **Excel Expo
 | Advanced Filtering | ❌ | ✅ | ❌ | ✅ |
 | Aggregation | ❌ | ✅ | ❌ | ✅ |
 | Pivot Mode | ❌ | ✅ | ❌ | ✅ |
+| Inline Cell Editing | ❌ | ✅ | ✅ | ✅ |
+| State Persistence | ❌ | ✅ | ❌ | ✅ |
 | **Price** | Free | **$$$** | Free (limited) | **Free** |
 
 ---

package/docs/API_REFERENCE.md

@@ -22,11 +22,15 @@ The main component for displaying and interacting with data.
 | `checkboxSelection` | `boolean` | `false` | Enable row selection via checkboxes. |
 | `pagination` | `boolean` | `false` | Enable the bottom pagination bar. |
 | `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | How to handle paging. |
-| `paginationModel` | `GridPaginationModel` | `{page:0, pageSize:25}` | Current page and page size. |
+| `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
+| `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Available page size options. |
 | `rowCount` | `number` | — | Total rows (required for server-side paging). |
+| `height` | `number \| string` | `undefined` | Total height of the grid container. |
+| `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density. |
 | `initialState` | `GridInitialState` | `undefined` | Starting state for sorting, filters, etc. |
 | `slots` | `GridSlots` | `{}` | Custom component overrides. |
-| `slotProps` | `Record<string, any>` | `{}` | Props passed to custom slots. |
+| `slotProps` | `Record<string, unknown>` | `{}` | Props passed to custom slots. |
 | `filterModel` | `GridFilterModel` | `undefined` | Active filters. |
 | `sortModel` | `GridSortItem[]` | `undefined` | Active sorting. |
 | `onRowClick` | `(params: GridRowParams) => void` | — | Fired when a row is clicked. |
@@ -54,8 +58,14 @@ Access these methods via the `apiRef` prop.
 | `sortColumn(field, dir)` | `void` | Programmatically sort a column. |
 | `getSortModel()` | `GridSortItem[]` | Get active sorting state. |
 | `setFilterModel(model)` | `void` | Programmatically set filters. |
+| `getFilterModel()` | `GridFilterModel` | Get the current filter model. |
 | `setPage(page)` | `void` | Change current page (0-indexed). |
+| `setPageSize(pageSize)` | `void` | Change the current page size. |
 | `scrollToIndexes(params)` | `void` | Scroll to specific row/column index. |
+| `getAllColumns()` | `GridColDef[]` | Get all defined columns. |
+| `getAggregationResult()` | `Record<string, unknown> \| null` | Get current aggregation results. |
+| `getAggregationModel()` | `GridAggregationModel \| null` | Get the active aggregation configuration. |
+| `copySelectedRows()` | `Promise<void>` | Copy selected rows to clipboard as TSV. |
 
 ---
 
@@ -71,7 +81,7 @@ Used in Tree Data and Row Grouping hierarchies.
 | `depth` | `number` | Nesting level (0 for root). |
 | `isExpanded` | `boolean` | Current expansion state. |
 | `children` | `GridRowId[]` | IDs of child nodes. |
-| `groupingValue` | `any` | The value this node is grouping by. |
+| `groupingValue` | `unknown` | The value this node is grouping by. |
 | `aggregatedValues` | `object` | Sums/Avgs computed for this group. |
 
 ---
@@ -81,21 +91,71 @@ Used in Tree Data and Row Grouping hierarchies.
 ### `GridColDef`
 Defines the behavior and appearance of a single column.
 
+#### Sizing & Layout
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `field` | `string` | — | **Required.** Unique identifier matching the row object key. |
+| `headerName` | `string` | — | Text shown in the column header cell. |
+| `description` | `string` | — | Tooltip shown on header hover (accessibility label). |
+| `width` | `number \| string` | `100` | Fixed width in pixels or a percentage string. |
+| `minWidth` | `number` | — | Minimum width in pixels (enforced during resize). |
+| `maxWidth` | `number` | — | Maximum width in pixels (enforced during resize). |
+| `flex` | `number` | — | Flex grow factor — distributes remaining space proportionally. Mutually exclusive with a fixed `width`. |
+| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment of cell content. |
+| `headerAlign` | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment of the header cell content. |
+
+#### Data & Type
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `type` | `'string' \| 'number' \| 'date' \| 'boolean' \| 'singleSelect' \| 'image'` | `'string'` | Data type — determines default filter operators and cell formatting. |
+| `valueOptions` | `Array<string \| number \| { value: unknown; label: string }>` | — | Allowed values for `type: 'singleSelect'` — used in the filter dropdown and edit cell. |
+| `valueGetter` | `(params: GridValueGetterParams) => unknown` | — | Derive a computed value from the row object. Runs before `valueFormatter` and `renderCell`. |
+| `valueFormatter` | `(params: GridValueFormatterParams) => string` | — | Format the value into a display string (e.g. currency, dates). Does not affect editing or sorting. |
+
+#### Rendering
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `renderCell` | `(params: GridRenderCellParams) => ReactNode` | Fully custom cell renderer. Receives `value`, `row`, `field`, `rowIndex`, `colIndex`. |
+| `renderHeader` | `(params: GridRenderHeaderParams) => ReactNode` | Custom header cell renderer. Use for icons, sort indicators, or rich headers. |
+| `renderEditCell` | `(params: GridRenderCellParams) => ReactNode` | Custom editor rendered when the cell enters edit mode. Requires `editable: true`. |
+
+#### Editing
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `editable` | `boolean` | `false` | Enables inline cell editing. Commit is handled by `DataGrid.processRowUpdate`. |
+
+#### Spanning
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `colSpan` | `number \| ((params: GridRenderCellParams) => number)` | Number of columns this cell merges horizontally. |
+| `rowSpan` | `number \| ((params: GridRenderCellParams) => number)` | Number of rows this cell merges vertically. |
+
+#### Styling
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `cellClassName` | `string \| ((params: GridRenderCellParams) => string)` | CSS class applied to every cell in this column. Use a function for conditional per-row styling. |
+| `headerClassName` | `string` | CSS class applied to the header cell. |
+
+#### Feature Flags
+
 | Property | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `field` | `string` | — | Unique identifier (matches row property). |
-| `headerName` | `string` | — | Text displayed in the header. |
-| `width` | `number` | `100` | Width in pixels. |
-| `type` | `'string' \| 'number' \| 'date' \| 'dateTime' \| 'boolean'` | `'string'` | Data type for formatting and filtering. |
-| `sortable` | `boolean` | `true` | Enable sorting for this column. |
-| `filterable` | `boolean` | `true` | Enable filtering for this column. |
-| `resizable` | `boolean` | `true` | Allow user to drag resize. |
-| `hideable` | `boolean` | `true` | Allow user to hide the column. |
-| `pinned` | `'left' \| 'right' \| null` | `null` | Sticky positioning. |
-| `exportable` | `boolean` | `true` | If `false`, column is excluded from all exports. |
-| `valueFormatter` | `(params: GridValueFormatterParams) => string` | — | Format value for display. |
-| `valueGetter` | `(params: GridValueGetterParams) => any` | — | Compute value from row data. |
-| `renderCell` | `(params: GridRenderCellParams) => ReactNode` | — | Custom cell renderer. |
+| `sortable` | `boolean` | `true` | Enable/disable sorting for this column. |
+| `filterable` | `boolean` | `true` | Enable/disable filtering for this column. |
+| `resizable` | `boolean` | `true` | Allow the user to drag-resize this column. |
+| `hideable` | `boolean` | `true` | Allow the user to hide this column via the panel. |
+| `pinnable` | `boolean` | `true` | Allow this column to be pinned via the UI. |
+| `disableColumnMenu` | `boolean` | `false` | Hide the column header kebab/context menu. |
+| `exportable` | `boolean` | `true` | Set to `false` to exclude from CSV, Excel, JSON, and Print exports. |
+| `groupable` | `boolean` | `true` | Allow this column to be used as a row grouping dimension. |
+| `aggregable` | `boolean` | `true` | Allow this column to be aggregated. |
+| `availableAggregationFunctions` | `string[]` | all built-ins | Restrict which aggregation functions are available for this column (e.g. `['sum', 'avg']`). |
 
 ---
 
@@ -126,17 +186,169 @@ Context provider for overriding the grid's visual system.
 ## 🛠️ Hooks
 
 ### `useGridApiRef()`
-Returns a ref to interact with the grid programmatically.
-- `state`: Access full internal state.
-- `getVisibleRows()`: Returns filtered/sorted rows.
-- `getVisibleColumns()`: Returns currently visible columns.
+
+Creates a typed ref to pass to the `apiRef` prop. Gives you imperative access to the grid after mount.
+
+```tsx
+import { useGridApiRef } from '@opencorestack/opengridx';
+
+const apiRef = useGridApiRef();
+
+// Pass to the grid
+<DataGrid apiRef={apiRef} rows={rows} columns={columns} />
+
+// Then call methods imperiously
+apiRef.current.scrollToIndexes({ rowIndex: 0 });
+apiRef.current.setFilterModel({ items: [] });
+```
+
+See the [Imperative API (`GridApi`)](#%EF%B8%8F-imperative-api-gridapi) table above for the full method list.
+
+---
 
 ### `useAggregation(params)`
-Compute summary values for datasets.
-- **Built-in Functions**: `sum`, `avg`, `min`, `max`, `count`, `unique`.
+
+Headless hook for computing column summaries outside of the built-in `aggregationModel` prop. Useful when you need aggregation results for a custom footer or external display.
+
+```tsx
+import { useAggregation } from '@opencorestack/opengridx';
+
+const { aggregationResult, isLoading } = useAggregation({
+  rows,
+  aggregationModel: { salary: 'sum', age: 'avg' },
+  isServerSide: false,
+});
+```
+
+#### Params (`UseAggregationParams`)
+
+| Param | Type | Description |
+| :--- | :--- | :--- |
+| `rows` | `GridRowModel[]` | The rows to aggregate. |
+| `aggregationModel` | `GridAggregationModel` | Map of `field → aggFn` (e.g. `{ salary: 'sum' }`). |
+| `isServerSide` | `boolean` | If `true`, skips client computation and uses `serverAggregationResults`. |
+| `filterModel` | `GridFilterModel` | Optional — restricts aggregation to filtered rows. |
+| `sortModel` | `GridSortItem[]` | Optional — used when `dataSource` is provided. |
+| `dataSource` | `GridDataSource` | Optional — server-side data adapter for async aggregation. |
+| `serverAggregationResults` | `GridAggregationResult \| null` | Pre-fetched results when `isServerSide: true`. |
+
+#### Return (`UseAggregationReturn`)
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `aggregationResult` | `GridAggregationResult` | Map of `field → computed value`. |
+| `isLoading` | `boolean` | `true` while a server-side fetch is in progress. |
+| `error` | `unknown` | Set if the server-side fetch threw. |
+
+**Built-in aggregation functions:** `sum`, `avg`, `min`, `max`, `count`, `unique`
+
+You can also use `formatAggregationValue(value, fnName)` to produce a display string from a raw result.
+
+---
+
+### `usePivot(rawRows, rawCols, model, enabled)`
+
+Headless hook that transforms a flat dataset into pivot rows and pivot column definitions. Pass the output directly to `<DataGrid rows={} columns={} />` when `pivotMode` is active.
+
+```tsx
+import { usePivot } from '@opencorestack/opengridx';
+
+const { pivotRows, pivotColumns, isValid } = usePivot(
+  rows,
+  columns,
+  {
+    rowFields: ['department'],
+    columnFields: ['year'],
+    valueFields: [{ field: 'revenue', aggFn: 'sum' }],
+  },
+  isPivotEnabled,
+);
+
+<DataGrid
+  rows={isPivotEnabled ? pivotRows : rows}
+  columns={isPivotEnabled ? pivotColumns : columns}
+/>
+```
+
+#### Parameters
+
+| Param | Type | Description |
+| :--- | :--- | :--- |
+| `rawRows` | `GridRowModel[]` | Original flat dataset. |
+| `rawCols` | `GridColDef[]` | Original column definitions. |
+| `model` | `GridPivotModel` | Pivot configuration — `rowFields`, `columnFields`, `valueFields`. |
+| `enabled` | `boolean` | When `false`, returns empty arrays immediately (no computation). |
+
+#### Return (`UsePivotReturn`)
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `pivotRows` | `GridRowModel[]` | Transformed rows ready for the grid. |
+| `pivotColumns` | `GridColDef[]` | Generated column definitions for each pivot key. |
+| `colKeys` | `string[]` | The distinct column pivot values used. |
+| `isValid` | `boolean` | `false` if the model is incomplete (e.g. no `rowFields` or `valueFields`). |
+
+#### `GridPivotModel`
+
+```ts
+interface GridPivotModel {
+  rowFields: string[];     // fields to group rows by
+  columnFields: string[];  // fields to spread as columns
+  valueFields: Array<{
+    field: string;
+    aggFn: 'sum' | 'avg' | 'count' | 'min' | 'max';
+    headerName?: string;
+  }>;
+}
+```
+
+---
 
 ### `useGridStateStorage(options)`
-Persist and restore grid configurations to LocalStorage or a backend.
+
+Persists grid state (sort, filters, pagination, column visibility, etc.) to `localStorage` and restores it on mount. Pass the returned values directly to `DataGrid`.
+
+```tsx
+import { useGridStateStorage } from '@opencorestack/opengridx';
+
+// Simple — just a storage key
+const { initialState, onStateChange } = useGridStateStorage('my-grid');
+
+// Advanced — with options
+const { initialState, onStateChange, clearState } = useGridStateStorage({
+  key: 'my-grid',
+  debounceMs: 500,                        // default: 300
+  include: ['sorting', 'filter', 'pagination'], // persist only these slices
+  storage: sessionStorage,                // default: localStorage
+});
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  initialState={initialState}
+  onStateChange={onStateChange}
+/>
+
+// Clear saved state (e.g. on a "Reset" button)
+<button onClick={clearState}>Reset Grid</button>
+```
+
+#### Options (`UseGridStateStorageOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `key` | `string` | — | **Required.** Storage key — use a unique value per grid instance. |
+| `debounceMs` | `number` | `300` | Debounce delay in ms before writing to storage. |
+| `include` | `(keyof GridState)[]` | all | Restrict which state slices are persisted. |
+| `storage` | `Storage` | `localStorage` | Any object implementing `getItem`/`setItem`/`removeItem` (e.g. `sessionStorage` or a custom backend adapter). |
+
+#### Return (`UseGridStateStorageReturn`)
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `initialState` | `GridState \| undefined` | Restored state from storage — pass to `DataGrid.initialState`. |
+| `onStateChange` | `(state: GridState) => void` | Callback to pass to `DataGrid.onStateChange`. |
+| `clearState` | `() => void` | Removes the saved state from storage. |
 
 ---
 
@@ -153,7 +365,7 @@ interface GridSortItem {
 ### `GridFilterModel`
 ```typescript
 interface GridFilterModel {
-  items: GridFilterItem[];
+  items?: (GridFilterItem | GridFilterGroup)[];
   logicOperator?: 'and' | 'or';
   quickFilterValues?: string[];
 }

package/docs/components/datagrid.md

@@ -29,8 +29,9 @@ function MyGrid() {
 | `loading` | `boolean` | `false` | Displays a loading skeleton/shimmer. |
 | `checkboxSelection` | `boolean` | `false` | Enable row checkboxes. |
 | `pagination` | `boolean` | `false` | Enable/Disable bottom pagination bar. |
-| `paginationModel` | `GridPaginationModel` | `{page:0, pageSize:25}` | Controlled pagination state. |
-| `initialState` | `GridState` | `undefined` | Initial configuration (sorting, columns, etc). |
+| `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Available page size options. |
+| `initialState` | `GridInitialState` | `undefined` | Initial configuration (sorting, columns, etc). |
 
 ## 🖱️ Interaction & Events
 
@@ -38,8 +39,9 @@ function MyGrid() {
 | :--- | :--- | :--- |
 | `onRowClick` | `(params) => void` | Fired when clicking a row body. |
 | `onCellClick` | `(params) => void` | Fired when clicking a specific cell. |
+| `onPaginationModelChange` | `(model: GridPaginationModel) => void` | Fired when page or page size changes. |
 | `onStateChange` | `(state) => void` | Fired on any internal state update. |
-| `processRowUpdate` | `(new, old) => R` | Fired after a cell edit is committed. |
+| `processRowUpdate` | `(new, old) => R \| Promise<R>` | Fired after a cell edit is committed. |
 
 ## 📦 Slots
 

package/docs/features/editing-reordering.md

@@ -82,18 +82,22 @@ const [colOrder, setColOrder] = useState(['id', 'name', 'status']);
 <DataGrid
   columnOrder={colOrder}
   onColumnOrderChange={(params) => {
-    // params.newOrder is the updated array of field strings
-    setColOrder(params.newOrder);
+    // 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);
   }}
 />
 ```
 
 ### Non-Reorderable Columns
-To prevent a specific column from being moved, set `reorderable: false` in its definition.
+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.
 
 ```tsx
-const columns = [
-  { field: 'id', reorderable: false }, // Stay pinned at start
-  { field: 'name' }
-];
+// Disable reordering globally
+<DataGrid disableColumnReorder />
+
+// Keep a column fixed by pinning it
+<DataGrid pinnedColumns={{ left: ['id'] }} />
 ```

package/docs/features/filtering.md

@@ -49,7 +49,7 @@ The `GridFilterModel` describes the current state of filters.
 
 ```typescript
 interface GridFilterModel {
-  items: GridFilterItem[];    // Active filter items
+  items?: (GridFilterItem | GridFilterGroup)[];  // Active filter items or groups
   logicOperator?: 'and' | 'or'; // How to combine items
   quickFilterValues?: string[]; // Values for the global search
 }
@@ -57,27 +57,29 @@ interface GridFilterModel {
 interface GridFilterItem {
   field: string;              // Column to filter
   operator: GridFilterOperator;
-  value?: any;                // Comparison value
+  value?: unknown;            // Comparison value
 }
 ```
 
 ### Supported Operators
 | Type | Operators |
 | :--- | :--- |
-| **String** | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty` |
-| **Number** | `=`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` |
-| **Date** | `is`, `not`, `after`, `before`, `isEmpty`, `isNotEmpty` |
+| **String** | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty`, `isAnyOf` |
+| **Number** | `equals`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` |
+| **Date** | `is`, `not`, `isEmpty`, `isNotEmpty` |
 | **Boolean** | `is` |
 
 ---
 
-## 🎨 Customizing Filter Components
-You can replace the default filter panel via the `slots` API:
+## 🎨 Customizing the Toolbar
+The filter panel is accessible through the built-in `GridToolbar`. To use your own toolbar that includes a filter entry point, pass a custom component to the `toolbar` slot:
 
 ```tsx
 <DataGrid
   slots={{
-    filterPanel: MyCustomFilterPanel
+    toolbar: MyCustomToolbar
   }}
 />
 ```
+
+The `FilterPanel` component is also exported from `@opencorestack/opengridx` if you need to embed it inside a custom layout.

package/docs/features/selection.md

@@ -47,7 +47,8 @@ const [selection, setSelection] = useState<GridRowId[]>([]);
 | `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. |
+| `onRowSelectionModelChange` | `(model: GridRowSelectionModel) => void` | — | Fired when the selection changes. |
+| `pinCheckboxColumn` | `boolean` | `false` | Keep the checkbox column visible during horizontal scroll. |
 
 ---
 

package/docs/features/sorting-pagination.md

@@ -52,7 +52,9 @@ When using `paginationMode="server"`, you must provide the `rowCount` and handle
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `pagination` | `boolean` | `false` | Enable/disable the pagination footer. |
-| `paginationMode` | `'client' \| 'server'` | `'client'` | Location of the pagination logic. |
+| `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | Location of the pagination logic. |
+| `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
+| `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
 | `pageSizeOptions` | `number[]` | `[10, 25, 50]` | Options for the rows-per-page selector. |
 
 ---

package/docs/features/state-persistence.md

@@ -63,5 +63,4 @@ The following features support state persistence:
 - **Filtering**: `filterModel`
 - **Pagination**: `paginationModel`
 - **Columns**: `columnVisibilityModel`, `columnOrder`, `pinnedColumns`, `columnWidths`
-- **Selection**: `rowSelectionModel`
-- **Grouping**: `rowGroupingModel`
+- **Density**: `density`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencorestack/opengridx",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "OpenGridX: High-performance React data infrastructure. Unlock advanced Row Grouping, Excel Export, and Column Pinning without the usual \"Pro\" gatekeeping. Built for speed, scale, and complete architectural freedom. Fully open, virtualization-ready, and feature-complete.",
   "type": "module",
   "main": "./dist/opengridx.umd.js",