@opencorestack/opengridx 0.1.5 → 0.1.7

package/docs/features/export-guide.md

@@ -0,0 +1,434 @@
+# Export Functionality Guide
+
+The DataGrid provides built-in export utilities for multiple formats. The standard exports (CSV, JSON, Print, basic Excel) have **zero dependencies**. The advanced Excel export uses [ExcelJS](https://github.com/exceljs/exceljs) loaded lazily.
+
+## Available Export Formats
+
+| Format | Function | Deps | Description |
+|---|---|---|---|
+| CSV | `exportToCsv` | none | Comma-separated values |
+| Excel (basic) | `exportToExcel` | none | HTML-table `.xls` trick |
+| **Excel (advanced)** | `exportToExcelAdvanced` | ExcelJS (lazy) | Real `.xlsx` with styles, types, multi-sheet |
+| JSON | `exportToJson` | none | Structured JSON |
+| Print | `printGrid` | none | Browser print dialog |
+
+---
+
+## Quick Start
+
+```tsx
+import { exportToCsv, exportToExcel, exportToExcelAdvanced, exportToJson, printGrid } from '@opencorestack/opengridx';
+
+// CSV
+exportToCsv(rows, columns, { fileName: 'data.csv' });
+
+// Basic Excel (no deps)
+exportToExcel(rows, columns, { fileName: 'data.xlsx' });
+
+// Advanced Excel (ExcelJS, lazy-loaded)
+await exportToExcelAdvanced(rows, columns, { fileName: 'data.xlsx' });
+
+// JSON
+exportToJson(rows, columns, { fileName: 'data.json', pretty: true });
+
+// Print
+printGrid(rows, columns, 'My Report');
+```
+
+---
+
+## 1. `exportToCsv`
+
+```tsx
+import { exportToCsv } from '@opencorestack/opengridx';
+
+exportToCsv(rows, columns, {
+  fileName: 'employees.csv',
+  includeHeaders: true,
+  delimiter: ',',
+  selectedRows: [1, 2, 3],           // export only these IDs
+  aggregationResult: aggResult,       // adds SUM/AVG totals row
+  aggregationModel: { salary: 'sum' },
+});
+```
+
+**`CsvExportOptions`:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fileName` | `string` | `'export.csv'` | Output filename |
+| `includeHeaders` | `boolean` | `true` | Include column header row |
+| `delimiter` | `string` | `','` | Field delimiter |
+| `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
+| `aggregationResult` | `object \| null` | — | Aggregation values row |
+| `aggregationModel` | `object \| null` | — | Labels for aggregation row |
+
+---
+
+## 2. `exportToExcel` (basic)
+
+HTML-table approach, no external libraries. Opens reliably in Excel and Numbers but as a legacy `.xls` format.
+
+```tsx
+import { exportToExcel } from '@opencorestack/opengridx';
+
+exportToExcel(rows, columns, {
+  fileName: 'report.xls',
+  sheetName: 'Data',
+  includeHeaders: true,
+  aggregationResult: aggResult,
+  aggregationModel: { salary: 'sum' },
+});
+```
+
+**`ExcelExportOptions`:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fileName` | `string` | `'export.xlsx'` | Output filename |
+| `sheetName` | `string` | `'Sheet1'` | Sheet tab name |
+| `includeHeaders` | `boolean` | `true` | Include column header row |
+| `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
+| `aggregationResult` | `object \| null` | — | Aggregation values row |
+| `aggregationModel` | `object \| null` | — | Labels for aggregation row |
+
+---
+
+## 3. `exportToExcelAdvanced` ⭐ (recommended)
+
+Generates a **real `.xlsx`** file using ExcelJS, loaded lazily (zero bundle-size impact unless called).
+
+```tsx
+import { exportToExcelAdvanced } from '@opencorestack/opengridx';
+
+// Simple — single sheet, all defaults
+await exportToExcelAdvanced(rows, columns, {
+  fileName: 'employees.xlsx',
+});
+
+// Full options — multi-sheet, custom styles
+await exportToExcelAdvanced(rows, columns, {
+  fileName: 'full-report.xlsx',
+
+  sheets: [
+    {
+      name: 'All Employees',
+      rows: 'all',              // or 'selected'
+      includeHeaders: true,
+      includeSummary: true,     // aggregation totals at bottom
+      autoFilter: true,         // dropdown filter buttons in header
+      frozenHeader: true,       // freeze row 1
+      alternateRowColor: '#f8fafc',
+    },
+    {
+      name: 'Selected Rows',
+      rows: 'selected',
+      includeHeaders: true,
+    },
+    {
+      type: 'summary',          // standalone aggregation sheet
+      name: 'Aggregation',
+    },
+  ],
+
+  columnStyles: {
+    salary:  { numFmt: '$#,##0.00', alignment: 'right' },
+    bonus:   { numFmt: '$#,##0.00', alignment: 'right' },
+    percent: { numFmt: '0.00%' },
+    joinDate:{ numFmt: 'yyyy-mm-dd' },
+  },
+
+  headerFillColor: '#1e3a5f',   // header row background
+  headerTextColor: '#e2e8f0',   // header row text
+  headerFontSize: 11,
+  bodyFontSize: 10,
+
+  aggregationResult: aggResult,
+  aggregationModel: { salary: 'sum', bonus: 'sum', score: 'avg' },
+  selectedRows: rowSelectionModel,
+});
+```
+
+### `ExcelAdvancedExportOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fileName` | `string` | `'export.xlsx'` | Output filename (`.xlsx` appended if missing) |
+| `sheets` | `ExcelSheetDefinition[]` | `[{ name: 'Data', rows: 'all' }]` | Sheet definitions |
+| `columnStyles` | `Record<string, ExcelColumnStyle>` | `{}` | Per-column style overrides |
+| `headerFillColor` | `string` | `'#f1f5f9'` | Header row background (`#rrggbb`) |
+| `headerTextColor` | `string` | `'#334155'` | Header row text color |
+| `headerFontSize` | `number` | `10` | Header font size (pt) |
+| `bodyFontSize` | `number` | `10` | Body font size (pt) |
+| `aggregationResult` | `object \| null` | — | Aggregation totals |
+| `aggregationModel` | `object \| null` | — | Aggregation function labels |
+| `selectedRows` | `(string\|number)[]` | — | IDs for `rows: 'selected'` sheets |
+
+### `ExcelSheetDefinition`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | — | Sheet tab name (max 31 chars) |
+| `rows` | `'all' \| 'selected'` | `'all'` | Which rows to include |
+| `includeHeaders` | `boolean` | `true` | Include column header row |
+| `includeSummary` | `boolean` | `false` | Aggregation totals rows at bottom |
+| `autoFilter` | `boolean` | `true` | Excel filter dropdowns on header |
+| `frozenHeader` | `boolean` | `true` | Freeze row 1 |
+| `alternateRowColor` | `string \| false` | `'#f8fafc'` | Odd-row fill. `false` to disable |
+
+### `ExcelColumnStyle`
+
+| Option | Type | Description |
+|---|---|---|
+| `numFmt` | `string` | Excel number format, e.g. `'$#,##0.00'`, `'0.00%'`, `'yyyy-mm-dd'` |
+| `width` | `number` | Column width in characters (overrides auto) |
+| `alignment` | `'left' \| 'center' \| 'right'` | Horizontal alignment |
+| `embedImage` | `boolean` | If true, URL in cell is fetched and embedded as image |
+| `imageWidth` | `number` | Width of embedded image (px, default: 40) |
+| `imageHeight`| `number` | Height of embedded image (px, default: 40) |
+
+### Summary Sheet
+
+Pass `{ type: 'summary', name: 'My Sheet' }` in `sheets` to add a standalone aggregation sheet:
+
+```
+| Column       | Function | Value     |
+|--------------|----------|-----------|
+| Salary       | SUM      | $8,320,000|
+| Bonus        | SUM      | $1,040,000|
+| Perf. Score  | AVG      | 3.7       |
+```
+
+### Feature Comparison: Basic vs Advanced
+
+| Feature | `exportToExcel` | `exportToExcelAdvanced` |
+|---|---|---|
+| True `.xlsx` format | ❌ HTML trick | ✅ |
+| Native number cells | ❌ text | ✅ |
+| Native date cells | ❌ text | ✅ |
+| Native boolean cells | ❌ text | ✅ |
+| Number format strings | ❌ | ✅ |
+| Bold / colored header | ❌ CSS ignored | ✅ |
+| Column widths | ❌ | ✅ auto from `colDef.width` |
+| Frozen header row | ❌ | ✅ |
+| Auto-filter dropdowns | ❌ | ✅ |
+| Alternating row colors | ❌ | ✅ |
+| Multi-sheet workbooks | ❌ | ✅ |
+| Aggregation totals row | Inline text | ✅ styled |
+| Standalone summary sheet | ❌ | ✅ |
+| Bundle impact | Zero | Zero (lazy-loaded) |
+
+---
+
+## 4. `exportToJson`
+
+```tsx
+import { exportToJson } from '@opencorestack/opengridx';
+
+exportToJson(rows, columns, {
+  fileName: 'data.json',
+  pretty: true,
+  aggregationResult: aggResult,
+  aggregationModel,
+  selectedRows: [1, 2, 3],
+});
+```
+
+When `aggregationResult` is provided, output shape becomes:
+```json
+{
+  "data": [...],
+  "aggregation": {
+    "labels": { "salary": "SUM" },
+    "values": { "salary": 8320000 }
+  }
+}
+```
+
+**`JsonExportOptions`:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fileName` | `string` | `'export.json'` | Output filename |
+| `pretty` | `boolean` | `true` | Pretty-print with indentation |
+| `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
+| `aggregationResult` | `object \| null` | — | Append aggregation object |
+| `aggregationModel` | `object \| null` | — | Function labels |
+
+---
+
+## 5. `printGrid`
+
+Opens a browser print dialog with a formatted table.
+
+```tsx
+import { printGrid } from '@opencorestack/opengridx';
+
+// Simple
+printGrid(rows, columns, 'Employee Report');
+
+// With options
+printGrid(rows, columns, {
+  title: 'Q1 Report',
+  selectedRows: [1, 2, 3],
+  aggregationResult: aggResult,
+  aggregationModel,
+});
+```
+
+**`PrintOptions`:**
+
+| Option | Type | Description |
+|---|---|---|
+| `title` | `string` | Print page title |
+| `selectedRows` | `(string\|number)[]` | Print only these row IDs |
+| `aggregationResult` | `object \| null` | Append totals |
+| `aggregationModel` | `object \| null` | Label totals |
+
+---
+
+## Common Patterns
+
+### Export with toolbar integration
+
+```tsx
+import { DataGrid, GridToolbar, exportToExcelAdvanced } from '@opencorestack/opengridx';
+
+function MyGrid() {
+  const [rows, setRows] = useState([...]);
+  const [columns] = useState([...]);
+  const [selected, setSelected] = useState([]);
+
+  return (
+    <DataGrid
+      rows={rows}
+      columns={columns}
+      checkboxSelection
+      rowSelectionModel={selected}
+      onRowSelectionModelChange={setSelected}
+      slots={{ toolbar: GridToolbar }}
+      slotProps={{
+        toolbar: {
+          onExcelAdvanced: () => exportToExcelAdvanced(rows, columns, {
+            fileName: 'report.xlsx',
+            selectedRows: selected,
+          }),
+        },
+      }}
+    />
+  );
+}
+```
+
+### Multi-sheet with selection
+
+```tsx
+await exportToExcelAdvanced(rows, columns, {
+  fileName: 'report.xlsx',
+  sheets: [
+    { name: 'All Data',      rows: 'all',      includeSummary: true },
+    { name: 'Selected',      rows: 'selected', includeSummary: false },
+    { type: 'summary',       name: 'Totals' },
+  ],
+  selectedRows: rowSelectionModel,
+  aggregationResult: aggResult,
+  aggregationModel: { salary: 'sum', bonus: 'sum' },
+});
+```
+
+### Respect `valueFormatter` for styled columns
+
+The advanced export keeps **raw values** for typed columns (`number`, `date`, `boolean`) so Excel can format them natively with `numFmt`. For `string` columns, `valueFormatter` is applied before writing.
+
+```tsx
+const columns: GridColDef[] = [
+  {
+    field: 'salary',
+    type: 'number',             // ← raw number written to Excel
+    valueFormatter: ({ value }) => `$${value.toLocaleString()}`, // used in CSV/print
+  },
+];
+
+await exportToExcelAdvanced(rows, columns, {
+  columnStyles: {
+    salary: { numFmt: '$#,##0.00' },  // ← Excel formats the native number
+  },
+});
+```
+
+---
+
+## Value Formatters
+
+All export functions respect `valueFormatter` and `valueGetter`:
+
+```tsx
+const columns: GridColDef[] = [
+  {
+    field: 'fullName',
+    valueGetter: ({ row }) => `${row.firstName} ${row.lastName}`,
+  },
+  {
+    field: 'salary',
+    valueFormatter: ({ value }) => `$${value.toLocaleString()}`,
+  },
+];
+```
+
+> **Note:** In `exportToExcelAdvanced`, `valueFormatter` is only applied for `string`-typed columns. For `number`/`date`/`boolean` columns, raw values are passed to Excel and formatted via `columnStyles.numFmt`.
+
+---
+
+## Excluding Columns
+
+You can exclude specific columns (e.g., action buttons or menus) from all export formats using the `exportable` property in the column definition. System columns are also automatically excluded.
+
+| Method | Description |
+|---|---|
+| `exportable: false` | Set in `GridColDef` to manually exclude any column |
+| `__check__` | Native checkbox column (auto-excluded) |
+| `__actions__` | Common field for action buttons (auto-excluded) |
+| `isSpacer: true` | Spacer columns (auto-excluded) |
+
+### Example
+```tsx
+const columns: GridColDef[] = [
+  { field: 'id', headerName: 'ID' },
+  { field: 'name', headerName: 'Name' },
+  { 
+    field: 'actions', 
+    headerName: 'Actions', 
+    exportable: false // This column won't appear in CSV/Excel/JSON/Print
+  },
+];
+```
+
+---
+
+## Performance Notes
+
+| Format | 10k rows | 100k rows |
+|---|---|---|
+| CSV | ~50ms | ~500ms |
+| JSON | ~80ms | ~800ms |
+| Excel (basic) | ~200ms | ~2s |
+| Excel (advanced) | ~300ms | ~3s |
+| Print | Best with paginated data | — |
+
+---
+
+## Browser Compatibility
+
+All export functions work in:
+- ✅ Chrome/Edge 90+
+- ✅ Firefox 88+
+- ✅ Safari 14+
+
+---
+
+## See Also
+
+- [Demo: Export Data](../demo/examples/ExportDemo.tsx)
+- [Demo: Advanced Excel Export](../demo/examples/AdvancedExcelExportDemo.tsx)
+- [Slots API Reference](./SLOTS_API.md)
+- [Theming Guide](./THEMING.md)

package/docs/features/filtering.md

@@ -0,0 +1,83 @@
+# 🔍 Filtering System
+
+OpenGridX provides a robust filtering system with support for both client-side and server-side operations.
+
+## 📑 Overview
+- **Quick Filter**: Search across all columns simultaneously.
+- **Column Filters**: Specific operators for different data types (string, number, date, etc.).
+- **Multi-Filter Groups**: Support for `AND`/`OR` logic operators.
+- **Server-Side Filtering**: Offload complex queries to your backend.
+
+---
+
+## 🛠️ Usage
+
+### Client-Side Filtering (Default)
+Simply define your columns with `filterable: true` (which is the default).
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={[
+    { field: 'name', headerName: 'Name' },
+    { field: 'age', headerName: 'Age', type: 'number' }
+  ]}
+/>
+```
+
+### Server-Side Filtering
+Set `filterMode="server"` and handle the request in your `dataSource`.
+
+```tsx
+<DataGrid
+  filterMode="server"
+  onFilterModelChange={(model) => console.log('Current Filters:', model)}
+  dataSource={{
+    getRows: async (params) => {
+      // params.filterModel contains the items and logic operators
+      return fetchRowsFromBackend(params);
+    }
+  }}
+/>
+```
+
+---
+
+## ⚙️ Filter Model API
+
+The `GridFilterModel` describes the current state of filters.
+
+```typescript
+interface GridFilterModel {
+  items: GridFilterItem[];    // Active filter items
+  logicOperator?: 'and' | 'or'; // How to combine items
+  quickFilterValues?: string[]; // Values for the global search
+}
+
+interface GridFilterItem {
+  field: string;              // Column to filter
+  operator: GridFilterOperator;
+  value?: any;                // Comparison value
+}
+```
+
+### Supported Operators
+| Type | Operators |
+| :--- | :--- |
+| **String** | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty` |
+| **Number** | `=`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` |
+| **Date** | `is`, `not`, `after`, `before`, `isEmpty`, `isNotEmpty` |
+| **Boolean** | `is` |
+
+---
+
+## 🎨 Customizing Filter Components
+You can replace the default filter panel via the `slots` API:
+
+```tsx
+<DataGrid
+  slots={{
+    filterPanel: MyCustomFilterPanel
+  }}
+/>
+```

package/docs/features/infinite-scroll.md

@@ -0,0 +1,87 @@
+# Infinite Scroll
+
+The OpenGridX DataGrid supports infinite scrolling (lazy loading), allowing you to load large datasets incrementally as the user scrolls.
+
+## Concept
+
+When infinite scroll is enabled, the grid:
+1.  Disables client-side slicing (pagination in the UI).
+2.  Uses `paginationModel` internally to track the current page and page size.
+3.  Triggers `onRowsScrollEnd` when the user scrolls near the bottom of the grid, signaling that more data should be fetched.
+4.  Data is typically **appended** to the existing rows, rather than replacing them.
+
+## Usage
+
+To enable infinite scrolling:
+
+1.  Set `pagination={false}` to disable UI pagination controls.
+2.  Set `paginationMode="infinite"`.
+3.  Implement `onRowsScrollEnd` to update your data fetching logic/state (e.g., increment page number).
+4.  Ensure your `dataSource` manages the loaded rows correctly (usually appending).
+
+```tsx
+import { DataGrid, GridDataSource } from '@opencorestack/opengridx';
+
+// ... setup columns and mockApi ...
+
+export default function InfiniteScrollDemo() {
+    const [paginationModel, setPaginationModel] = useState({
+        page: 0,
+        pageSize: 50
+    });
+    const [loading, setLoading] = useState(false);
+    const [allRows, setAllRows] = useState([]);
+
+    const dataSource: GridDataSource = useMemo(() => ({
+        getRows: async (params) => {
+            setLoading(true);
+            try {
+                // Fetch NEXT batch of rows from server
+                const response = await mockApi.getRows(params);
+                
+                // CRITICAL: Append new rows to existing rows
+                // (Or ensure response.rows contains ONLY new rows and parent handles appending)
+                return response;
+            } finally {
+                setLoading(false);
+            }
+        }
+    }), []);
+
+    const handleScrollEnd = useCallback(() => {
+        if (!loading) {
+            // Increment page to fetch next batch
+            setPaginationModel(prev => ({
+                ...prev,
+                page: prev.page + 1
+            }));
+        }
+    }, [loading]);
+
+    return (
+        <DataGrid
+            rows={[]} // Rows managed by dataSource
+            columns={columns}
+            dataSource={dataSource}
+            
+            // KEY PROPS FOR INFINITE SCROLL
+            pagination={false} 
+            paginationMode="infinite"
+            sortingMode="server"
+            
+            paginationModel={paginationModel}
+            onPaginationModelChange={setPaginationModel}
+            
+            onRowsScrollEnd={handleScrollEnd}
+        />
+    );
+}
+```
+
+## Implementation Details
+
+*   **`onRowsScrollEnd`**: Triggered when `scrollHeight - scrollTop - clientHeight < threshold` (default 100px).
+*   **Request Handling**: `useGridDataSource` includes logic to cancel stale requests if scrolling happens too quickly.
+*   **Appending vs Replacing**: 
+    *   In `infinite` mode, rows fetched for **new pages** are appended.
+    *   Rows fetched due to **sorting/filtering changes** replace the entire dataset (resetting to page 0).

package/docs/features/list-view.md

@@ -0,0 +1,65 @@
+# 📱 List View
+
+Switch from a multi-column grid to a single-column detailed list. Perfect for mobile responsiveness or card-based layouts.
+
+---
+
+## 🏗️ Usage
+
+Enable List View by passing the `listView` prop. You must also provide a `listViewColumn` object which defines how each "Card" should be rendered.
+
+```tsx
+const listColDef: GridListViewColDef<Employee> = {
+  field: 'card',
+  renderCell: (params) => <MyEmployeeCard row={params.row} />
+};
+
+<DataGrid
+  listView={true}
+  listViewColumn={listColDef}
+  rows={rows}
+  columns={columns} // Fallback columns for standard grid view
+/>
+```
+
+---
+
+## 🎨 Styling
+
+When `listView` is active:
+- **Header is Hidden**: The standard column header row disappears.
+- **Full Width**: The row container becomes a vertical stack where the `renderCell` output takes 100% of the available width.
+- **Card Containers**: Each row maintains its standard selection and hover behaviors, but visually acts as a card.
+
+### Custom Card Rendering
+The `renderCell` function in `listViewColumn` receives all standard `GridRenderCellParams`, allowing you to build rich, complex UIs for each item.
+
+```tsx
+function MyEmployeeCard({ row }) {
+  return (
+    <div className="employee-card">
+       <Avatar src={row.avatar} />
+       <div className="info">
+          <h3>{row.name}</h3>
+          <p>{row.role}</p>
+       </div>
+       <div className="status">{row.status}</div>
+    </div>
+  );
+}
+```
+
+---
+
+## 📱 Responsive Toggle
+
+A common pattern is to toggle List View based on screen width:
+
+```tsx
+const isMobile = window.innerWidth < 768;
+
+<DataGrid
+  listView={isMobile}
+  // ...
+/>
+```