@opencorestack/opengridx 0.1.5 → 0.1.7

package/docs/API_REFERENCE.md

@@ -0,0 +1,177 @@
+# 📖 OpenGridX API Reference
+
+This document provides a comprehensive reference for all exported types, interfaces, and utility functions in the OpenGridX library.
+
+---
+
+## 🏗️ Core Components
+
+### `<DataGrid />`
+The main component for displaying and interacting with data.
+
+#### Props
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `rows` | `GridRowModel[]` | `[]` | Array of data objects. |
+| `columns` | `GridColDef[]` | `[]` | Definitions for the columns. |
+| `getRowId` | `(row: GridRowModel) => GridRowId` | `row.id` | Returns a unique identifier for each row. |
+| `rowHeight` | `number` | `52` | Height of each row in pixels. |
+| `headerHeight` | `number` | `56` | Height of the header row. |
+| `autoHeight` | `boolean` | `false` | Adjust grid height to match row total. |
+| `loading` | `boolean` | `false` | Shows a loading skeleton overlay. |
+| `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. |
+| `rowCount` | `number` | — | Total rows (required for server-side paging). |
+| `initialState` | `GridInitialState` | `undefined` | Starting state for sorting, filters, etc. |
+| `slots` | `GridSlots` | `{}` | Custom component overrides. |
+| `slotProps` | `Record<string, any>` | `{}` | 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. |
+| `onCellClick` | `(params: GridCellParams) => void` | — | Fired when a cell is clicked. |
+| `onStateChange` | `(state: GridState) => void` | — | Fired on any internal state update. |
+| `processRowUpdate` | `(new, old) => R \| Promise<R>` | — | Fired after a cell edit is committed. |
+| `dataSource` | `GridDataSource` | — | Remote data provider interface. |
+
+---
+
+## 🕹️ Imperative API (`GridApi`)
+
+Access these methods via the `apiRef` prop.
+
+| Method | Return | Description |
+| :--- | :--- | :--- |
+| `getRow(id)` | `GridRowModel \| null` | Get row data by ID. |
+| `getAllRows()` | `GridRowModel[]` | Get all loaded rows. |
+| `getVisibleRows()` | `GridRowModel[]` | Get rows after filtering/sorting. |
+| `getColumn(field)` | `GridColDef \| null` | Get column definition by field. |
+| `getVisibleColumns()` | `GridColDef[]` | Get currently visible columns. |
+| `selectRow(id, isSelected)` | `void` | Set selection for a single row. |
+| `selectRows(ids, isSelected)`| `void` | Set selection for multiple rows. |
+| `getSelectedRows()` | `GridRowId[]` | Get IDs of all selected rows. |
+| `sortColumn(field, dir)` | `void` | Programmatically sort a column. |
+| `getSortModel()` | `GridSortItem[]` | Get active sorting state. |
+| `setFilterModel(model)` | `void` | Programmatically set filters. |
+| `setPage(page)` | `void` | Change current page (0-indexed). |
+| `scrollToIndexes(params)` | `void` | Scroll to specific row/column index. |
+
+---
+
+## 🌳 Internal Data Structures
+
+### `GridTreeNode`
+Used in Tree Data and Row Grouping hierarchies.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `GridRowId` | Unique ID of the row. |
+| `parentId` | `GridRowId \| null` | ID of the parent node. |
+| `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. |
+| `aggregatedValues` | `object` | Sums/Avgs computed for this group. |
+
+---
+
+## 📑 Column Definitions
+
+### `GridColDef`
+Defines the behavior and appearance of a single column.
+
+| 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. |
+
+---
+
+## 📂 Export Utilities
+
+| Function | Return | Description |
+| :--- | :--- | :--- |
+| `exportToCsv(rows, cols, options?)` | `void` | Triggers download of CSV file. |
+| `exportToJson(rows, cols, options?)` | `void` | Triggers download of JSON file. |
+| `exportToExcel(rows, cols, options?)` | `void` | Basic `.xls` export (zero-dep). |
+| `exportToExcelAdvanced(rows, cols, options?)` | `Promise<void>` | Real `.xlsx` export (styled, multi-sheet, lazy-loaded). |
+| `printGrid(rows, cols, title \| options)` | `void` | Opens browser print dialog. |
+
+---
+
+## 🎨 Theming & Styling
+
+### `DataGridThemeProvider`
+Context provider for overriding the grid's visual system.
+
+#### `GridTheme` Object
+- **Colors**: `primary`, `secondary`, `header`, `border`, `rowHover`, `rowSelected`.
+- **Typography**: `fontFamily`, `fontSize`, `fontWeight`.
+- **Spacing**: `cellPadding`, `headerHeight`, `rowHeight`.
+
+---
+
+## 🛠️ 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.
+
+### `useAggregation(params)`
+Compute summary values for datasets.
+- **Built-in Functions**: `sum`, `avg`, `min`, `max`, `count`, `unique`.
+
+### `useGridStateStorage(options)`
+Persist and restore grid configurations to LocalStorage or a backend.
+
+---
+
+## ⚙️ Interfaces & Types
+
+### `GridSortItem`
+```typescript
+interface GridSortItem {
+  field: string;
+  sort: 'asc' | 'desc';
+}
+```
+
+### `GridFilterModel`
+```typescript
+interface GridFilterModel {
+  items: GridFilterItem[];
+  logicOperator?: 'and' | 'or';
+  quickFilterValues?: string[];
+}
+```
+
+### `GridPaginationModel`
+```typescript
+interface GridPaginationModel {
+  page: number;
+  pageSize: number;
+}
+```
+
+### `GridPivotModel`
+```typescript
+interface GridPivotModel {
+  rowFields: string[];
+  columnFields: string[];
+  valueFields: { field: string; aggFn: string; headerName?: string }[];
+}
+```

package/docs/README.md

@@ -0,0 +1,60 @@
+# 📚 OpenGridX Documentation
+
+![OpenGridX Banner](assets/banner.png)
+
+Welcome to the official documentation for **OpenGridX**, the high-performance React DataGrid library.
+
+🚀 **[Live Interactive Documentation](https://opencorestack.github.io/OpenGridX/)** | 🔍 **[API Reference](API_REFERENCE.md)**
+
+---
+
+## 🏗️ Base Components API
+Detailed reference for the core structural components.
+
+- **[DataGrid](components/datagrid.md)** - The main component and props
+- **[Header](components/header.md)** - Column headers and grouping
+- **[Row](components/row.md)** - Row rendering and states
+- **[Cell](components/cell.md)** - Individual cell logic and rendering
+- **[Toolbar](components/toolbar.md)** - Global grid actions
+- **[Pagination](components/pagination.md)** - Navigation and paging
+- **[Filter Panel](components/filter-panel.md)** - Advanced filter UI
+- **[Tooltip](components/tooltip.md)** - Dynamic UI tooltips
+- **[Column Visibility](components/column-visibility.md)** - Managing visible fields
+- **[Column Grouping](components/column-group-header.md)** - Multi-level nested headers
+- **[Column Resizing](components/column-resize.md)** - Dynamic width controls
+---
+
+## 🚀 Features
+In-depth guides on the grid's functional capabilities.
+
+- **[Virtualization](features/virtualization.md)** - Handling massive datasets
+- **[Filtering & Search](features/filtering.md)** - Column filters and Global Quick Search
+- **[Sorting & Pagination](features/sorting-pagination.md)** - Organizing and navigating data
+- **[Editing & Reordering](features/editing-reordering.md)** - Inline edits and Drag-and-Drop
+- **[Loading & Performance](features/loading-states.md)** - Skeletons, Lazy, and Infinite loading
+- **[Row Selection](features/selection.md)** - Multi & single choice selection
+- **[Clipboard](features/clipboard.md)** - Copy and Paste grid data
+- **[Pinning](features/pinning.md)** - Sticky columns and rows
+- **[State Persistence](features/state-persistence.md)** - Save/Restore grid configuration
+- **[Aggregation & Pivot](features/aggregation-pivot.md)** - Data summarization and analytics
+- **[Tree Data & Grouping](features/tree-data-grouping.md)** - Hierarchical layout and Column grouping
+- **[Cell Spanning](features/cell-spanning.md)** - Row and Col span spanning
+- **[Master-Detail](features/master-detail.md)** - Expandable Detail Panels
+- **[List View](features/list-view.md)** - Card-based responsive layout
+- **[Infinite Scroll](features/infinite-scroll.md)** - Advanced performance loading
+- **[Data Source](features/data-source.md)** - Server-side fetching and SSR
+- **[Export Guide](features/export-guide.md)** - Excel, CSV, JSON, and Print
+
+---
+
+## 🎨 Customization
+Make the grid your own.
+
+- **[Theming Guide](customization/theming.md)** - CSS variables and branding
+- **[Slots API](customization/slots-api.md)** - Replacing internal components
+
+---
+
+## 🛠️ Project Meta
+- **[Development Roadmap](roadmap.md)** - What's built and what's next
+- **[Research Notes](research/FEATURE_CATALOG.md)** - Comparative analysis and design decisions

package/docs/components/cell.md

@@ -0,0 +1,44 @@
+# `<Cell />`
+
+The atomic unit of the grid. Handles rendering, formatting, editing, and selection states for a single data point.
+
+## ⚙️ Props
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `any` | The raw value to display. |
+| `row` | `GridRowModel` | The full row data object. |
+| `colDef` | `GridColDef` | Configuration for the column. |
+| `rowIndex` | `number` | 0-indexed position in the current view. |
+| `isSelected` | `boolean` | Whether the parent row is selected. |
+| `isFocused` | `boolean` | Whether the cell has keyboard focus. |
+| `isEditable` | `boolean` | Enables inline editing for this cell. |
+| `isEditing` | `boolean` | Whether the cell is currently in edit mode. |
+| `width` | `number` | Calculated width including resizing and flex. |
+| `pinnedPosition` | `'left' \| 'right' \| null` | Sticky positioning state. |
+
+## 🧩 Modifiers & Classes
+
+The `<Cell />` component applies various BEM classes for styling:
+- `.ogx__cell--selected`: When the row is selected.
+- `.ogx__cell--focused`: When focused via keyboard.
+- `.ogx__cell--editing`: During active cell editing.
+- `.ogx__cell--pinned-left`: Sticky to the left.
+- `.ogx__cell--pinned-right`: Sticky to the right.
+
+## 🛠️ Custom Rendering
+
+Use the `renderCell` property in your `GridColDef` to override the default content:
+
+```tsx
+const columns: GridColDef[] = [
+  {
+    field: 'status',
+    renderCell: (params) => (
+      <Tag color={params.value === 'active' ? 'green' : 'red'}>
+        {params.value}
+      </Tag>
+    )
+  }
+];
+```

package/docs/components/column-group-header.md

@@ -0,0 +1,57 @@
+# `<ColumnGroupHeader />`
+
+The `ColumnGroupHeader` component handles the rendering of nested header groups in multi-level column layouts. It allows for advanced data organization where multiple columns are grouped under a single, semantic parent.
+
+## 📑 Overview
+- **Hierarchical Layout**: Supports an unlimited depth of nested groupings (Year → Quarter → Metric).
+- **Sticky Behavior**: Automatically stays within the grid's header section during horizontal scroll.
+- **Dynamic Calculation**: Positions itself based on the combined width of its child columns.
+- **Reflective Styles**: Inherits header-level styling while providing specialized group-level CSS hooks.
+
+---
+
+## 🛠️ Usage
+
+### Define Multi-Level Grouping
+In your columns definition, include nested `columnGroups`.
+
+```tsx
+const columns = [
+  { field: 'id', headerName: 'ID', width: 100 },
+  { field: 'q1', headerName: 'Q1 Sales', width: 120 },
+  { field: 'q2', headerName: 'Q2 Sales', width: 120 },
+];
+
+// Define your mapping logic in your component or use the columns API:
+// ColumnGroupHeader is typically used by the DataGrid automatically when 
+// nested structures are detected.
+```
+
+### Direct Customization
+While the grid uses this component internally, you can customize its appearance via specific CSS classes or by replacing it in the `slots` API.
+
+---
+
+## ⚙️ How it Works
+
+1. **Hierarchy Resolution**: The component takes a structure and determines which headers need to be "merged" into groups.
+2. **Width Aggregation**: Each group header calculates its own total width by summing the widths of all its children (including other nested groups).
+3. **Alignment**: Ensuring that the group labels are centered over their respective child columns for a clean visual hierarchy.
+
+---
+
+## 🎨 Slot Implementation
+Replace the system's group header with a custom one for specialized styling or interactions.
+
+```tsx
+<DataGrid
+  slots={{
+    columnGroupHeader: MyCustomGroupHeader
+  }}
+/>
+```
+
+## 📝 Best Practices
+- **Logical Labels**: Use clear, concise labels for groups like `2024 Performance` or `Contact Info`.
+- **Type-Based Grouping**: Align related data types (e.g., all currency fields under a `Finance` group) for better user comprehension.
+- **Limit Depth**: While technically unlimited, more than 3-4 levels of nesting can become difficult for users to follow on small screens.

package/docs/components/column-resize.md

@@ -0,0 +1,63 @@
+# `<ColumnResizeHandle />` & Resizing
+
+OpenGridX supports dynamic column resizing, allowing users to adjust the width of any column on the fly for better visibility of data. This is facilitated by the `ColumnResizeHandle`, which sits invisibly between adjacent column headers.
+
+## 📑 Overview
+- **Inter-Header Interaction**: A handle is placed on the right edge of each resizable column header.
+- **Visual Feedback**: On hover and during drag, the grid provides immediate visual cues.
+- **Constraints**: Supports `minWidth` and `maxWidth` values defined in your `GridColDef`.
+- **Double-Click Action**: Support for auto-sizing columns to fit their longest content is built-in.
+
+---
+
+## 🛠️ Usage
+
+### Basic Resizing
+By default, all columns are resizable. You can disable it for a specific field.
+
+```tsx
+const columns: GridColDef[] = [
+  { field: 'id', headerName: 'ID', resizable: false },  // Fixed width
+  { field: 'name', headerName: 'Name', minWidth: 100 }  // User can resize
+];
+```
+
+### Grid-Wide Control
+Disable resizing globally via the `DataGrid` props.
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  disableColumnResize
+/>
+```
+
+---
+
+## ⚙️ How it Works
+
+1. **Handle Deployment**: At the end of each `Header` component, a `ColumnResizeHandle` is mounted.
+2. **Drag Event Processing**: When the handle is dragged:
+   - It calculates the change in horizontal position (`deltaX`).
+   - It applies this change to the column's current width in the grid's state.
+3. **Boundaries Enforcement**: If the new width is less than `minWidth` (default 50px) or more than `maxWidth`, the change is rejected.
+4. **Finalization**: On mouse up, the new column width is persisted to the grid's `columnVisibilityModel` equivalents.
+
+---
+
+## 🎨 Slot Implementation
+In the DataGrid, you can replace the default handle component for custom styling (e.g., a thicker line or different colors).
+
+```tsx
+<DataGrid
+  slots={{
+    columnResizeHandle: MyCustomHandle
+  }}
+/>
+```
+
+## 📝 Best Practices
+- **Define Min Widths**: Always set a reasonable `minWidth` so columns don't accidentally become 0px wide.
+- **Persistence**: Listen to `onColumnWidthChange` to save the user's preferred layout for their next visit.
+- **Content Fit**: Remember that large data values might hide behind narrow columns; use tooltips for overflow coverage.

package/docs/components/column-visibility.md

@@ -0,0 +1,61 @@
+# `<ColumnVisibilityPanel />`
+
+The `ColumnVisibilityPanel` provides an interactive list for users to toggle the visibility of specific columns within the grid. This is essential for managing dense datasets where only a subset of information is needed at once.
+
+## 📑 Overview
+- **Auto-Generating List**: It automatically builds a list of all togglable columns from the grid's state.
+- **Searchable Interface**: Includes a quick search to find specific columns in grids with many fields.
+- **Toggle State**: Synchronizes instantly with the grid's `columnVisibilityModel`.
+- **Exclusion Logic**: Automatically hides special internal columns (e.g., checkboxes) and columns marked with `hideable: false`.
+
+---
+
+## 🛠️ Usage
+
+### Toolbar Integration
+The most common way to use the visibility panel is within a dropdown menu in the grid's toolbar.
+
+```tsx
+import { ColumnVisibilityPanel } from '@opencorestack/opengridx';
+
+// In your Toolbar component
+<Dropdown content={<ColumnVisibilityPanel />}>
+  <button>Columns</button>
+</Dropdown>
+```
+
+### Direct Integration
+You can also render it persistently beside the grid or within a custom modal.
+
+```tsx
+<div className="my-column-sidebar">
+  <ColumnVisibilityPanel />
+</div>
+```
+
+---
+
+## ⚙️ How it Works
+
+1. **Column Resolution**: The panel retrieves all columns defined in the `DataGrid`.
+2. **Filtration**: It ignores columns that should not be visible in the list:
+   - Columns starting with `__` (internal types).
+   - Columns explicitly marked as `hideable: false` in the `GridColDef`.
+3. **State Management**: When a user toggles a switch, it triggers an update to the grid's `columnVisibilityModel`, causing the grid to re-render only the affected columns.
+
+---
+
+## 🎨 Slot Implementation
+In advanced scenarios, you can replace the default panel with your own implementation using the `columnVisibilityPanel` slot.
+
+```tsx
+<DataGrid
+  slots={{
+    columnVisibilityPanel: MyCustomVisibilityPanel
+  }}
+/>
+```
+
+## 📝 Best Practices
+- **Logical Grouping**: Ensure your columns have clear, human-readable `headerName` values so they are easily identifiable in the list.
+- **Persistent State**: Use `onColumnVisibilityModelChange` to save column preferences to local storage or a database so the user's layout is preserved.

package/docs/components/datagrid.md

@@ -0,0 +1,70 @@
+# `<DataGrid />`
+
+The central component of the OpenGridX library. Highly optimized for performance with virtualization and a rich feature set.
+
+## 🚀 Usage
+
+```tsx
+import { DataGrid } from '@opencorestack/opengridx';
+
+function MyGrid() {
+  return (
+    <DataGrid
+      rows={rows}
+      columns={columns}
+      height={600}
+    />
+  );
+}
+```
+
+## ⚙️ Core Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `rows` | `R[]` | `[]` | The dataset to display. |
+| `columns` | `GridColDef[]` | `[]` | Column definitions. |
+| `getRowId` | `(row: R) => GridRowId` | `row.id` | Unique ID for each row. |
+| `height` | `number \| string` | `undefined` | Height of the grid container. |
+| `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). |
+
+## 🖱️ Interaction & Events
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `onRowClick` | `(params) => void` | Fired when clicking a row body. |
+| `onCellClick` | `(params) => void` | Fired when clicking a specific cell. |
+| `onStateChange` | `(state) => void` | Fired on any internal state update. |
+| `processRowUpdate` | `(new, old) => R` | Fired after a cell edit is committed. |
+
+## 📦 Slots
+
+Customize internal components using the `slots` prop.
+
+```tsx
+<DataGrid
+  slots={{
+    toolbar: MyCustomToolbar,
+    pagination: MyCustomPagination,
+    noRowsOverlay: MyEmptyState
+  }}
+/>
+```
+
+---
+
+## 🔗 Related Components
+- [Row](row.md)
+- [Cell](cell.md)
+- [Header](header.md)
+- [Toolbar](toolbar.md)
+- [Filter Panel](filter-panel.md)
+- [Pagination](pagination.md)
+- [Tooltip](tooltip.md)
+- [Column Visibility](column-visibility.md)
+- [Column Grouping](column-group-header.md)
+- [Column Resizing](column-resize.md)

package/docs/components/filter-panel.md

@@ -0,0 +1,26 @@
+# `<FilterPanel />`
+
+A persistent UI component for managing complex multi-column filter rules.
+
+## ⚙️ Key Concepts
+
+The Filter Panel allows users to define a list of `GridFilterItem` objects. Each item consists of:
+- **Field**: Which column to filter.
+- **Operator**: How to compare (e.g., `contains`, `equals`, `>`, `is empty`).
+- **Value**: The target value for comparison.
+
+## 🔌 Integration
+
+The `<DataGrid />` manages the visibility of the Filter Panel via its internal state. It is usually triggered from the Column Menu or the Toolbar.
+
+## 📝 Configuration
+
+Filter operators are automatically determined based on the column's `type`:
+- `string`: contains, equals, startsWith, endsWith, isAnyOf.
+- `number`: =, !=, >, >=, <, <=.
+- `date` / `dateTime`: is, isNot, isAfter, isBefore.
+- `boolean`: isTrue, isFalse.
+
+## 🎨 Slot Usage
+
+While the Filter Panel is a complex internal component, its appearance can be influenced by CSS variables or by providing a custom implementation to the `filterPanel` slot in advanced use cases.

package/docs/components/header.md

@@ -0,0 +1,39 @@
+# `<Header />`
+
+Manages the column headers, sorting triggers, column resizing, and column grouping rows.
+
+## ⚙️ Props
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `columns` | `GridColDef[]` | Column definitions for the visible viewport. |
+| `columnGroupingModel` | `GridColumnGroupingModel` | Hierarchy for multi-level header spanning. |
+| `sortModel` | `GridSortModel` | Current sorting state for highlight and icons. |
+| `onSort` | `(field, direction) => void` | Callback triggered when a header is clicked. |
+| `onColumnResize` | `Function` | Callback for manual column width changes. |
+| `pinnedColumns` | `GridColumnPinning` | Coordinates sticky positioning for headers. |
+| `checkboxSelection` | `boolean` | Renders the "Select All" checkbox. |
+
+## 📐 Column Grouping
+
+The `<Header />` dynamically calculates the nesting depth of your `columnGroupingModel` and renders additional [Column Group Headers](column-group-header.md) above the main column headers.
+
+```tsx
+const columnGroupingModel = [
+  {
+    groupId: 'internal',
+    headerName: 'Internal Details',
+    children: ['id', 'path'],
+  }
+];
+```
+
+## 🖱️ Column Menu & Resizing
+
+Unless `disableColumnMenu` is set to `true` in a column's `GridColDef`, each header cell renders a menu icon. In addition, the header facilitates manual [Column Resizing](column-resize.md).
+
+Clicking the menu icon opens a popover with actions to:
+- Sort Asc/Desc
+- Pin Left/Right/None
+- Hide Column
+- Manage Columns (Open [Visibility Panel](column-visibility.md))

package/docs/components/pagination.md

@@ -0,0 +1,34 @@
+# `<Pagination />`
+
+Handles row limit selection and page navigation. Compatible with both client-side and server-side data modes.
+
+## ⚙️ Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `page` | `number` | `0` | The current active page (0-indexed). |
+| `pageSize` | `number` | `100` | Number of rows per page. |
+| `rowCount` | `number` | `0` | Total number of rows (used to calculate page count). |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options for the "Rows per page" dropdown. |
+
+## 🕹️ Interaction
+
+The pagination component communicates state changes back to the `<DataGrid />` via:
+- `onPageChange`: Triggered when clicking Next/Prev or a page number.
+- `onPageSizeChange`: Triggered when changing the rows-per-page limit.
+
+## 🔄 Modes
+
+- **Client-side**: Pagination happens automatically on the local `rows` array.
+- **Server-side**: Pagination state is passed to the `GridDataSource` to fetch new chunks of data.
+
+## 🎨 Customizing
+You can replace the internal pagination UI using the `pagination` slot:
+
+```tsx
+<DataGrid
+  slots={{
+    pagination: MyCustomPaginationComponent
+  }}
+/>
+```

package/docs/components/row.md

@@ -0,0 +1,31 @@
+# `<Row />`
+
+Manages a horizontal collection of cells. Includes support for selection, expansion (Detail Panels), row pinning, and reordering.
+
+## ⚙️ Props
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `row` | `GridRowModel` | The data object for this row. |
+| `columns` | `GridColDef[]` | Columns currently visible in the viewport. |
+| `rowIndex` | `number` | Index used for virtualization and alternating colors. |
+| `isSelected` | `boolean` | Checkbox / Selection state. |
+| `checkboxSelection` | `boolean` | If `true`, renders the selection checkbox. |
+| `hasDetailPanel` | `boolean` | Enables the detail panel toggle icon. |
+| `isDetailPanelExpanded` | `boolean` | Current expansion state. |
+| `rowReordering` | `boolean` | Enables the drag handle for reordering rows. |
+| `rowHeight` | `number` | Height in pixels (default: 52). |
+
+## 📐 Row Pinning
+
+Rows can be pinned to the **Top** or **Bottom** of the grid using the `pinnedRows` prop on the `<DataGrid />`. Pinned rows are rendered using the same `<Row />` component but are positioned sticky within their own containers.
+
+## 🌈 Alternating Colors
+
+The grid supports "Zebra" striping via CSS:
+- `.ogx__row--even`: Even-indexed rows.
+- `.ogx__row--odd`: Odd-indexed rows.
+
+## 📋 Detail Panel
+
+When `getDetailPanelContent` is provided, the `<Row />` renders an expandable container below itself to show supplemental data.