@opencorestack/opengridx 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# OpenGridX — Changelog
+
+**Package**: `@opencorestack/opengridx`
+**License**: MIT © 2026 Open Core Stack
+
+---
+
+## [0.1.0] — March 6, 2026 🚀
+
+> **Status: ✅ RELEASE READY — 100% feature-complete for v0.1.0 scope**
+
+This is the initial public release of OpenGridX. All planned v0.1.0 features are implemented, tested, and included in the production bundle.
+
+### ✅ Core Features
+- **High-Performance Virtualization** — Custom row + column virtual scrolling engine, 60fps at 100k+ rows
+- **Multi-Column Sorting** — Client-side and server-side; stable multi-field sort
+- **Advanced Filtering** — 11+ operators (contains, equals, startsWith, etc.) with AND/OR filter builder UI
+- **Pagination** — Client-side and server-side modes with configurable page sizes
+- **Row Selection** — Single and multi-row checkbox selection with `rowSelectionModel` controlled/uncontrolled API
+
+### ✅ Advanced UI & Layout
+- **Column Pinning** — Left and right sticky columns with correct z-index layering
+- **Row Pinning** — Top and bottom pinned rows with visual separation
+- **Column Resizing** — Throttled drag-to-resize at 60fps with minimum width enforcement
+- **Column Reordering** — Drag-and-drop column reorder
+- **Row Reordering** — Drag-and-drop row reorder with `onRowOrderChange` callback
+- **Detail Panels** — Expandable master-detail rows via `getDetailPanelContent`
+- **Cell & Row Spanning** — `colSpan` and `rowSpan` support for merged-cell layouts
+- **List View Mode** — Card-based responsive layout via `listView` / `listViewColumn`
+- **Column Grouping** — Multi-level column header groups via `columnGroupingModel`
+- **Toolbar** — Built-in toolbar with column visibility, filter, and density controls; fully replaceable via `slots`
+
+### ✅ Data Management
+- **Inline Cell Editing** — Double-click or Enter to edit; `editable` per column; `processRowUpdate` callback
+- **Tree Data** — Client-side hierarchical rows via `treeData` + `getTreeDataPath`
+- **Row Grouping** — Group rows by column value with collapsible groups and aggregation summaries
+- **Aggregation** — SUM, AVG, COUNT, MIN, MAX in group footers and global sticky footer
+- **Pivot Mode** — Multidimensional data pivoting via `pivotMode` + `pivotModel`
+
+### ✅ Server-Side Integration
+- **Data Source API** — `useGridDataSource` hook for unified server-side fetching
+- **Server-Side Sorting, Filtering & Pagination** — All offloaded cleanly to the backend
+- **Infinite Scroll** — Viewport-triggered batch-loading (`paginationMode="infinite"`)
+- **Server-Side Tree Data** — Lazy children loading via `dataSource.getChildren`
+- **Server-Side Aggregation** — Fetch summary totals directly from API responses
+
+### ✅ Export
+- **CSV Export** — `exportToCsv()` utility, respects `valueFormatter`
+- **Excel Export** — Basic `.xlsx` via `exportToExcel()`; advanced pixel-perfect image-embedded export via `exportToExcelAdvanced()` (lazy-loads ExcelJS)
+- **JSON Export** — `exportToJson()`
+- **Print** — `printGrid()` with print-optimised CSS
+
+### ✅ Clipboard
+- **Keyboard Copy** — `Ctrl+C` / `Cmd+C` copies selected rows as TSV (tab-separated values)
+- **Programmatic Copy** — `apiRef.current.copySelectedRows()` for button-triggered copying
+- **Excel/Sheets Compatible** — TSV output pastes cleanly into any spreadsheet app
+- **Smart Focus Handling** — Does not intercept `Ctrl+C` in text inputs; correctly handles checkbox-focused grid cells
+
+### ✅ Theming
+- **`DataGridThemeProvider`** — React context-based global theming
+- **5 Built-in Themes** — `darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compactTheme`
+- **CSS Variables** — Full `--ogx-*` token system; Shadow DOM compatible
+- **`cellClassName` / `headerClassName`** — Per-column custom class injection
+
+### ✅ Accessibility (WCAG 2.1 AA)
+- Semantic ARIA roles: `grid`, `row`, `gridcell`, `columnheader`
+- `aria-sort`, `aria-selected`, `aria-expanded`, `aria-readonly`, `aria-label` throughout
+- Full keyboard navigation: Arrow keys, Tab, Enter, Escape, Home/End, PageUp/PageDown
+- Visible focus ring in keyboard mode (CSS classname-toggled, zero React state overhead)
+
+### ✅ State Persistence
+- **`initialState` prop** — Restore column widths, visibility, sort, and filter on mount
+- **`useGridStateStorage(key)` hook** — Auto-saves to `localStorage`; pluggable storage backend
+
+### ✅ Developer Experience
+- **`apiRef`** — Full imperative API: `getSelectedRows`, `copySelectedRows`, `selectRow`, `sortColumn`, `setFilterModel`, `getVisibleRows`, `scrollToIndexes`, and more
+- **`slots` System** — Replace Toolbar, Pagination, NoRowsOverlay, LoadingOverlay, Footer
+- **`slotProps`** — Pass custom props to slot components
+- **TypeScript** — 100% typed; full `index.d.ts` output via `vite-plugin-dts`
+- **Zero UI Dependencies** — No Ant Design, MUI, or Radix. Pure React + vanilla CSS (BEM)
+
+### 📦 Bundle
+| Artifact | Minified | Gzipped |
+|---|---|---|
+| `opengridx.es.js` (ES Module) | 226 KB | **52 KB** |
+| `opengridx.umd.js` (UMD) | 1,089 KB | 315 KB |
+| `opengridx.css` | 59 KB | **10 KB** |
+| `exceljs` (lazy, Excel export only) | 1,385 KB | 302 KB |
+
+---
+
+## 🗺️ Planned for v0.2.0
+
+- **Rich Excel Styling** — Bold headers, background fill, border styles natively via ExcelJS (no post-processing)
+- **Cell Range Clipboard** — Select a rectangular cell region (mouse drag), copy to clipboard, paste from Excel back into editable cells
+
+---
+
+*Last Updated: March 6, 2026*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Core Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# OpenGridX | The Free Enterprise React DataGrid
+
+![OpenGridX Hero Banner](docs/assets/banner.png)
+
+**OpenGridX** is a premium, high-performance React DataGrid engine designed to break the "Pay-to-Play" model in the React ecosystem. It provides a pure-custom, zero-dependency alternative to enterprise grids like **MUI X DataGrid Pro** and **AG Grid**, offering advanced features for free.
+
+---
+
+## 🚀 Why OpenGridX?
+Most React grids gatekeep essential features like **Row Grouping**, **Excel Export**, and **Master-Detail** behind expensive annual licenses. OpenGridX provides these premium capabilities out-of-the-box, with full source-code control and no external UI dependencies.
+
+---
+
+## 🚀 Live Demo & Documentation
+Explore the interactive showcase and full API documentation online:
+👉 **[opencorestack.github.io/OpenGridX](https://opencorestack.github.io/OpenGridX/)**
+
+---
+
+## 🚀 Key Features
+
+- **High-Performance Virtualization**: Custom-built engine handling 100,000+ rows and columns at 60fps.
+- **Advanced Layouts**: Native support for **Row & Column Spanning**, Grouping, and Tree Data.
+- **Premium UX**: Built-in glassmorphism, smooth micro-animations, and responsive headers.
+- **Data Orchestration**: 11+ filter operators, multi-column sorting, and robust pagination.
+- **Zero UI Dependencies**: 100% vanilla CSS (BEM) and pure React/TypeScript logic.
+- **Skeleton Loader**: Built-in animated loading states with smart column detection.
+- **Fully Customizable**: Slots system for replacing any component (pagination, overlays, toolbar).
+- **Export Functionality**: Built-in CSV, Excel, JSON, and Print export (zero dependencies).
+
+## 🎨 Customization & Extensibility
+
+### Slots System
+
+Replace any built-in component with your own custom implementation:
+
+```tsx
+import { Select } from 'antd'; // or any UI library
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  slots={{
+    toolbar: CustomToolbar,
+    pagination: CustomPaginationComponent,
+    noRowsOverlay: CustomEmptyState,
+    loadingOverlay: CustomLoader,
+    footer: CustomFooter
+  }}
+  slotProps={{
+    toolbar: { /* custom props */ },
+    pagination: { /* custom props */ }
+  }}
+/>
+```
+
+**Use Case Examples:**
+- Custom toolbars with export buttons, filters, actions
+- Replace pagination with Ant Design, MUI, or custom components
+- Custom loading states and empty states
+- Brand-specific footers and overlays
+
+📖 **[Full Customization Guide](docs/customization/slots-api.md)**
+
+### Export Functionality
+
+OpenGridX has **two tiers of Excel export** — basic built-in (zero dependencies) and advanced rich export (optional ExcelJS).
+
+```tsx
+import {
+    exportToCsv,
+    exportToExcel,          // ✅ built-in, zero deps
+    exportToExcelAdvanced,  // ✅ rich .xlsx — requires: npm install exceljs
+    exportToJson,
+    printGrid
+} from '@opencorestack/opengridx';
+
+// CSV — zero dependencies
+exportToCsv(rows, columns, { fileName: 'data.csv' });
+
+// Basic Excel — zero dependencies
+// Generates an HTML-based .xlsx that opens perfectly in Excel/Sheets
+exportToExcel(rows, columns, { fileName: 'data.xlsx' });
+
+// Advanced Excel — requires ExcelJS (npm install exceljs)
+// Real binary .xlsx with: styled headers, image embedding,
+// multi-sheet, aggregation rows, frozen headers, auto-filter
+exportToExcelAdvanced(rows, columns, {
+    fileName: 'data.xlsx',
+    columnStyles: {
+        avatar: { embedImage: true, imageWidth: 40, imageHeight: 40 }
+    }
+});
+
+// JSON — zero dependencies
+exportToJson(rows, columns, { fileName: 'data.json' });
+
+// Print — zero dependencies
+printGrid(rows, columns, 'Report Title');
+```
+
+> **Optional peer dependency:** `exportToExcelAdvanced` requires ExcelJS for rich `.xlsx` generation. Install it only when needed:
+> ```bash
+> npm install exceljs
+> ```
+> All other export functions (`exportToExcel`, `exportToCsv`, `exportToJson`, `printGrid`) work with **zero extra dependencies**.
+
+### Skeleton Loader
+
+Built-in animated skeleton rows during data loading:
+- Automatically adapts to column definitions
+- Dynamically calculates placeholder columns based on viewport width
+- Smooth shimmer animation for professional UX
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  loading={isLoading}  // Shows skeleton automatically
+/>
+```
+
+## ⚡ Performance & Bundle Size
+
+OpenGridX is built for speed and efficiency. The core library is lightweight, with heavier features loaded on-demand.
+
+| Component | Minified Size | Gzipped (Transfer) | Status |
+| :--- | :--- | :--- | :--- |
+| **Core Library** (`opengridx.es.js`) | **220 KB** | **51 KB** | ✅ Highly Optimized |
+| **Excel Extension** (`exceljs.min...js`) | **1.38 MB** | **301 KB** | ✅ Progressively Loaded |
+| **Styles** (`opengridx.css`) | **58 KB** | **9 KB** | ✅ Lean & Themeable |
+
+### Optimization Highlights:
+- **Progressive Loading**: Heavy dependencies like `ExcelJS` are only fetched when the advanced export feature is triggered via `exportToExcelAdvanced`.
+- **Tree-shaking Ready**: Built as an ES Module to ensure your bundler (Vite, Webpack, etc.) only includes what you use.
+- **Zero UI Dependencies**: No bulky third-party component libraries. Just pure React and optimized CSS.
+- **Efficient Rendering**: Uses custom virtualization and optimized CSS classes to handle 100k+ rows with zero lag.
+
+## 📁 Project Structure
+
+- `lib/`: Core library source.
+- `demo/`: Interactive showcase and feature testing dashboard.
+- `docs/`: Technical research, catalogs, and architectural analysis.
+- `.agent/`: Master project context and automation workflows.
+
+## 🛠️ Getting Started
+
+### Installation
+
+```bash
+npm install @opencorestack/opengridx
+```
+
+```tsx
+// Styles are automatically included — no separate CSS import needed
+import { DataGrid } from '@opencorestack/opengridx';
+```
+
+> **Note:** Styles are bundled inside the component. If you need to import them manually (e.g., for SSR or CSS-in-JS setups):
+> ```tsx
+> import '@opencorestack/opengridx/styles';
+> ```
+
+## 📚 Documentation
+
+Detailed documentation is available in the [docs/](docs/README.md) directory.
+
+### 🏛️ Components API
+- **[DataGrid](docs/components/datagrid.md)** - Main component props and slots
+- **[Header](docs/components/header.md)** - Column headers and grouping
+- **[Row & Cell](docs/components/row.md)** - Row and Cell customization
+- **[Toolbar & Pagination](docs/components/toolbar.md)** - Supplemental UI components
+
+### 🚀 Core Features
+- **[Virtualization](docs/features/virtualization.md)** - 60fps rendering for 100k+ rows
+- **[Filtering & Search](docs/features/filtering.md)** - Quick filters and advanced operators
+- **[Sorting & Pagination](docs/features/sorting-pagination.md)** - Multi-column organization
+- **[Editing & Reordering](docs/features/editing-reordering.md)** - Inline edits and Drag-and-Drop
+- **[Loading & Performance](docs/features/loading-states.md)** - Skeletons, Lazy, and Infinite loading
+- **[Row Selection](docs/features/selection.md)** - Checkbox and multi-row interaction
+- **[Pinning](docs/features/pinning.md)** - Sticky columns and rows
+- **[State Persistence](docs/features/state-persistence.md)** - Save/Restore grid configuration
+- **[Infinite Scroll](docs/features/infinite-scroll.md)** - Seamless lazy-loading
+
+### 📊 Advanced Data
+- **[Aggregation & Pivot](docs/features/aggregation-pivot.md)** - Summary totals and multidimensional data
+- **[Tree Data & Grouping](docs/features/tree-data-grouping.md)** - Hierarchical display and Column Grouping
+- **[Cell Spanning](docs/features/cell-spanning.md)** - Colspan and Rowspan implementation
+- **[Master-Detail](docs/features/master-detail.md)** - Expandable Detail Panels
+- **[List View](docs/features/list-view.md)** - Responsive card-based layout
+- **[Export Guide](docs/features/export-guide.md)** - Excel, CSV, and Print functionality
+- **[Data Source](docs/features/data-source.md)** - Connecting to backend APIs
+
+### 🎨 Customization
+- **[Theming Guide](docs/customization/theming.md)** - Visual styles and CSS variables
+- **[Slots API](docs/customization/slots-api.md)** - Component replacement system
+- **[Custom Pagination](docs/features/custom-pagination.md)** - Custom paging UI
+
+## 📊 Development Status
+
+Currently in **Phase 4: Server-Side Integration**. 
+All core UI features (Pinning, Spanning, Tree Data, Grouping, Skeleton Loading, Custom Components) are fully implemented and verified in the [demo app](demo/).
+
+### Recent Updates
+- ✅ Skeleton loader with dynamic column calculation
+- ✅ Slots system for component customization
+- ✅ Fixed horizontal scrolling for wide tables
+- ✅ Enhanced empty states
+
+---
+
+## 📝 License
+MIT © 2026 Open Core Stack