@opencorestack/opengridx 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +195 -118
  3. package/dist/opengridx.es.js +194 -194
  4. package/dist/opengridx.es.js.map +1 -1
  5. package/dist/opengridx.umd.js +12 -40
  6. package/dist/opengridx.umd.js.map +1 -1
  7. package/package.json +1 -12
  8. package/dist/exceljs.min-CrbHmMCD.js +0 -22597
  9. package/dist/exceljs.min-CrbHmMCD.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,20 @@
5
5
 
6
6
  ---
7
7
 
8
+ ## [0.1.1] — March 6, 2026 🔧
9
+
10
+ ### Fixed
11
+ - ExcelJS correctly marked as external in Vite build config (consistent with `peerDependencies`)
12
+ - Clipboard programmatic copy button now correctly reads live selection state via `apiRef.getSelectedRows()`
13
+ - `Ctrl+C` keyboard shortcut now works when grid checkboxes are focused
14
+
15
+ ### Improved
16
+ - Package size reduced from 8.4 MB → 1.8 MB unpacked (ExcelJS no longer bundled)
17
+ - README rewritten with Getting Started first, basic example, and full API reference table
18
+ - Cleaned devDependencies (removed unused `strip-comment`, `strip-comments`)
19
+
20
+ ---
21
+
8
22
  ## [0.1.0] — March 6, 2026 🚀
9
23
 
10
24
  > **Status: ✅ RELEASE READY — 100% feature-complete for v0.1.0 scope**
package/README.md CHANGED
@@ -4,39 +4,160 @@
4
4
 
5
5
  **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.
6
6
 
7
+ 👉 **[Live Demo & Docs](https://opencorestack.github.io/OpenGridX/)** — Interactive showcase with full API documentation
8
+
7
9
  ---
8
10
 
9
- ## 🚀 Why OpenGridX?
10
- 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.
11
+ ## 🛠️ Getting Started
12
+
13
+ ### Installation
14
+
15
+ ```bash
16
+ npm install @opencorestack/opengridx
17
+ ```
18
+
19
+ ```tsx
20
+ // Styles are automatically included — no separate CSS import needed
21
+ import { DataGrid } from '@opencorestack/opengridx';
22
+ ```
23
+
24
+ > **Note:** Styles are bundled inside the component. For SSR or CSS-in-JS setups use the explicit styles export:
25
+ > ```tsx
26
+ > import '@opencorestack/opengridx/styles';
27
+ > ```
11
28
 
12
29
  ---
13
30
 
14
- ## 🚀 Live Demo & Documentation
15
- Explore the interactive showcase and full API documentation online:
16
- 👉 **[opencorestack.github.io/OpenGridX](https://opencorestack.github.io/OpenGridX/)**
31
+ ## ⚡ Basic Example
32
+
33
+ ```tsx
34
+ import { DataGrid, GridColDef } from '@opencorestack/opengridx';
35
+
36
+ const columns: GridColDef[] = [
37
+ { field: 'id', headerName: 'ID', width: 70 },
38
+ { field: 'name', headerName: 'Name', width: 180 },
39
+ { field: 'role', headerName: 'Role', width: 150 },
40
+ { field: 'salary', headerName: 'Salary', width: 120, type: 'number',
41
+ valueFormatter: ({ value }) => `$${value.toLocaleString()}` },
42
+ { field: 'department', headerName: 'Department', width: 160 },
43
+ ];
44
+
45
+ const rows = [
46
+ { id: 1, name: 'Jon Snow', role: 'Engineer', salary: 95000, department: 'Defense' },
47
+ { id: 2, name: 'Cersei Lannister', role: 'Manager', salary: 140000, department: 'Management' },
48
+ { id: 3, name: 'Arya Stark', role: 'Analyst', salary: 65000, department: 'Special Ops' },
49
+ ];
50
+
51
+ export default function App() {
52
+ return (
53
+ <DataGrid
54
+ rows={rows}
55
+ columns={columns}
56
+ checkboxSelection
57
+ pagination
58
+ height={400}
59
+ />
60
+ );
61
+ }
62
+ ```
17
63
 
18
64
  ---
19
65
 
20
66
  ## 🚀 Key Features
21
67
 
22
- - **High-Performance Virtualization**: Custom-built engine handling 100,000+ rows and columns at 60fps.
68
+ - **High-Performance Virtualization**: Custom-built engine handling 100,000+ rows at 60fps.
23
69
  - **Advanced Layouts**: Native support for **Row & Column Spanning**, Grouping, and Tree Data.
24
- - **Premium UX**: Built-in glassmorphism, smooth micro-animations, and responsive headers.
25
70
  - **Data Orchestration**: 11+ filter operators, multi-column sorting, and robust pagination.
26
71
  - **Zero UI Dependencies**: 100% vanilla CSS (BEM) and pure React/TypeScript logic.
27
72
  - **Skeleton Loader**: Built-in animated loading states with smart column detection.
28
73
  - **Fully Customizable**: Slots system for replacing any component (pagination, overlays, toolbar).
29
- - **Export Functionality**: Built-in CSV, Excel, JSON, and Print export (zero dependencies).
74
+ - **Export Functionality**: Built-in CSV, Excel, JSON, and Print export.
75
+ - **Clipboard**: `Ctrl+C` / `Cmd+C` copies selected rows as TSV for Excel/Sheets.
76
+ - **Accessibility**: WCAG 2.1 AA — full ARIA roles and keyboard navigation.
77
+ - **Theming**: CSS variable API with 5 built-in themes + custom theme support.
78
+
79
+ ---
80
+
81
+ ## 📐 API Reference
82
+
83
+ ### Core Props
84
+
85
+ | Prop | Type | Default | Description |
86
+ | :--- | :--- | :--- | :--- |
87
+ | `rows` | `GridRowModel[]` | — | **Required.** Array of data rows. |
88
+ | `columns` | `GridColDef[]` | — | **Required.** Column definitions. |
89
+ | `height` | `number` | `500` | Grid height in pixels. |
90
+ | `loading` | `boolean` | `false` | Shows skeleton loader when `true`. |
91
+ | `checkboxSelection` | `boolean` | `false` | Enables checkbox column for row selection. |
92
+ | `pagination` | `boolean` | `false` | Enables client-side pagination. |
93
+ | `pageSize` | `number` | `25` | Rows per page. |
94
+ | `getRowId` | `(row) => GridRowId` | `row.id` | Custom row ID accessor. |
95
+ | `rowHeight` | `number` | `52` | Row height in pixels. |
96
+ | `headerHeight` | `number` | `56` | Header height in pixels. |
97
+
98
+ ### Selection
99
+
100
+ | Prop | Type | Description |
101
+ | :--- | :--- | :--- |
102
+ | `rowSelectionModel` | `GridRowId[]` | Controlled selected row IDs. |
103
+ | `onRowSelectionModelChange` | `(model: GridRowId[]) => void` | Fires on selection change. |
104
+ | `disableRowSelectionOnClick` | `boolean` | Prevent row click from toggling selection. |
105
+
106
+ ### Sorting & Filtering
107
+
108
+ | Prop | Type | Description |
109
+ | :--- | :--- | :--- |
110
+ | `sortModel` | `GridSortItem[]` | Controlled sort model. |
111
+ | `onSortModelChange` | `(model) => void` | Fires on sort change. |
112
+ | `filterModel` | `GridFilterModel` | Controlled filter model. |
113
+ | `onFilterModelChange` | `(model) => void` | Fires on filter change. |
114
+ | `disableColumnFilter` | `boolean` | Disables column-level filtering. |
115
+
116
+ ### Server-Side
117
+
118
+ | Prop | Type | Description |
119
+ | :--- | :--- | :--- |
120
+ | `paginationMode` | `'client' \| 'server' \| 'infinite'` | Data fetching mode. |
121
+ | `sortingMode` | `'client' \| 'server'` | Where sorting is applied. |
122
+ | `filterMode` | `'client' \| 'server'` | Where filtering is applied. |
123
+ | `dataSource` | `GridDataSource` | Server-side data adapter. |
124
+ | `rowCount` | `number` | Total rows for server-side pagination. |
125
+
126
+ ### Customization
127
+
128
+ | Prop | Type | Description |
129
+ | :--- | :--- | :--- |
130
+ | `slots` | `GridSlots` | Replace built-in components (toolbar, pagination, overlays). |
131
+ | `slotProps` | `GridSlotProps` | Pass custom props to slot components. |
132
+ | `getRowClassName` | `(params) => string` | Add custom CSS class to rows. |
133
+ | `getCellClassName` | `(params) => string` | Add custom CSS class to cells. |
134
+ | `theme` | `GridTheme` | Apply a custom theme object. |
135
+
136
+ ### `apiRef` — Imperative API
137
+
138
+ ```tsx
139
+ const apiRef = useGridApiRef();
140
+ <DataGrid apiRef={apiRef} ... />
141
+
142
+ // Usage
143
+ apiRef.current.getSelectedRows() // → GridRowId[]
144
+ apiRef.current.copySelectedRows() // → Promise<void>
145
+ apiRef.current.selectRow(id, true) // select a row
146
+ apiRef.current.setFilterModel(model) // programmatic filter
147
+ apiRef.current.sortColumn('name', 'asc')
148
+ apiRef.current.setPage(2)
149
+ apiRef.current.getVisibleRows() // → GridRowModel[]
150
+ ```
151
+
152
+ ---
30
153
 
31
154
  ## 🎨 Customization & Extensibility
32
155
 
33
156
  ### Slots System
34
157
 
35
- Replace any built-in component with your own custom implementation:
158
+ Replace any built-in component with your own:
36
159
 
37
160
  ```tsx
38
- import { Select } from 'antd'; // or any UI library
39
-
40
161
  <DataGrid
41
162
  rows={rows}
42
163
  columns={columns}
@@ -54,17 +175,9 @@ import { Select } from 'antd'; // or any UI library
54
175
  />
55
176
  ```
56
177
 
57
- **Use Case Examples:**
58
- - Custom toolbars with export buttons, filters, actions
59
- - Replace pagination with Ant Design, MUI, or custom components
60
- - Custom loading states and empty states
61
- - Brand-specific footers and overlays
62
-
63
- 📖 **[Full Customization Guide](docs/customization/slots-api.md)**
64
-
65
178
  ### Export Functionality
66
179
 
67
- OpenGridX has **two tiers of Excel export** — basic built-in (zero dependencies) and advanced rich export (optional ExcelJS).
180
+ OpenGridX has **two tiers of Excel export**:
68
181
 
69
182
  ```tsx
70
183
  import {
@@ -75,139 +188,103 @@ import {
75
188
  printGrid
76
189
  } from '@opencorestack/opengridx';
77
190
 
78
- // CSV — zero dependencies
79
191
  exportToCsv(rows, columns, { fileName: 'data.csv' });
80
-
81
- // Basic Excel — zero dependencies
82
- // Generates an HTML-based .xlsx that opens perfectly in Excel/Sheets
83
192
  exportToExcel(rows, columns, { fileName: 'data.xlsx' });
84
-
85
- // Advanced Excel — requires ExcelJS (npm install exceljs)
86
- // Real binary .xlsx with: styled headers, image embedding,
87
- // multi-sheet, aggregation rows, frozen headers, auto-filter
88
193
  exportToExcelAdvanced(rows, columns, {
89
194
  fileName: 'data.xlsx',
90
- columnStyles: {
91
- avatar: { embedImage: true, imageWidth: 40, imageHeight: 40 }
92
- }
195
+ columnStyles: { avatar: { embedImage: true, imageWidth: 40, imageHeight: 40 } }
93
196
  });
94
-
95
- // JSON — zero dependencies
96
197
  exportToJson(rows, columns, { fileName: 'data.json' });
97
-
98
- // Print — zero dependencies
99
198
  printGrid(rows, columns, 'Report Title');
100
199
  ```
101
200
 
102
- > **Optional peer dependency:** `exportToExcelAdvanced` requires ExcelJS for rich `.xlsx` generation. Install it only when needed:
201
+ > **Optional peer dependency:** `exportToExcelAdvanced` requires ExcelJS:
103
202
  > ```bash
104
203
  > npm install exceljs
105
204
  > ```
106
- > All other export functions (`exportToExcel`, `exportToCsv`, `exportToJson`, `printGrid`) work with **zero extra dependencies**.
107
205
 
108
- ### Skeleton Loader
109
-
110
- Built-in animated skeleton rows during data loading:
111
- - Automatically adapts to column definitions
112
- - Dynamically calculates placeholder columns based on viewport width
113
- - Smooth shimmer animation for professional UX
206
+ ### Theming
114
207
 
115
208
  ```tsx
116
- <DataGrid
117
- rows={rows}
118
- columns={columns}
119
- loading={isLoading} // Shows skeleton automatically
120
- />
121
- ```
209
+ import { DataGridThemeProvider, darkTheme } from '@opencorestack/opengridx';
122
210
 
123
- ## ⚡ Performance & Bundle Size
124
-
125
- OpenGridX is built for speed and efficiency. The core library is lightweight, with heavier features loaded on-demand.
126
-
127
- | Component | Minified Size | Gzipped (Transfer) | Status |
128
- | :--- | :--- | :--- | :--- |
129
- | **Core Library** (`opengridx.es.js`) | **220 KB** | **51 KB** | ✅ Highly Optimized |
130
- | **Excel Extension** (`exceljs.min...js`) | **1.38 MB** | **301 KB** | ✅ Progressively Loaded |
131
- | **Styles** (`opengridx.css`) | **58 KB** | **9 KB** | ✅ Lean & Themeable |
211
+ <DataGridThemeProvider theme={darkTheme}>
212
+ <DataGrid rows={rows} columns={columns} />
213
+ </DataGridThemeProvider>
214
+ ```
132
215
 
133
- ### Optimization Highlights:
134
- - **Progressive Loading**: Heavy dependencies like `ExcelJS` are only fetched when the advanced export feature is triggered via `exportToExcelAdvanced`.
135
- - **Tree-shaking Ready**: Built as an ES Module to ensure your bundler (Vite, Webpack, etc.) only includes what you use.
136
- - **Zero UI Dependencies**: No bulky third-party component libraries. Just pure React and optimized CSS.
137
- - **Efficient Rendering**: Uses custom virtualization and optimized CSS classes to handle 100k+ rows with zero lag.
216
+ Built-in themes: `darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compactTheme`
138
217
 
139
- ## 📁 Project Structure
218
+ ---
140
219
 
141
- - `lib/`: Core library source.
142
- - `demo/`: Interactive showcase and feature testing dashboard.
143
- - `docs/`: Technical research, catalogs, and architectural analysis.
144
- - `.agent/`: Master project context and automation workflows.
220
+ ## ⚡ Performance & Bundle Size
145
221
 
146
- ## 🛠️ Getting Started
222
+ | Artifact | Minified | Gzipped | Notes |
223
+ | :--- | :--- | :--- | :--- |
224
+ | **Core ES Module** (`opengridx.es.js`) | 220 KB | **52 KB** | Use this — tree-shakeable |
225
+ | **Core UMD** (`opengridx.umd.js`) | 146 KB | **44 KB** | CommonJS / CDN compat |
226
+ | **Styles** (`opengridx.css`) | 57 KB | **9 KB** | Auto-included |
227
+ | **ExcelJS** (optional peer dep) | — | — | `npm install exceljs` |
228
+ | **npm package download** | — | **400 KB** | Total compressed tarball |
147
229
 
148
- ### Installation
230
+ - **Tree-shaking Ready**: ES Module build — bundlers (Vite, Webpack) only include what you use.
231
+ - **Zero UI Dependencies**: No MUI, Ant Design, or Radix. Pure React + vanilla CSS.
232
+ - **Lazy Advanced Export**: ExcelJS is an optional peer dep — not bundled, only used if you install it.
233
+ - **Efficient Rendering**: Custom virtualization handles 100k+ rows with zero DOM churn.
149
234
 
150
- ```bash
151
- npm install @opencorestack/opengridx
152
- ```
235
+ ---
153
236
 
154
- ```tsx
155
- // Styles are automatically included — no separate CSS import needed
156
- import { DataGrid } from '@opencorestack/opengridx';
157
- ```
237
+ ## 📚 Documentation
158
238
 
159
- > **Note:** Styles are bundled inside the component. If you need to import them manually (e.g., for SSR or CSS-in-JS setups):
160
- > ```tsx
161
- > import '@opencorestack/opengridx/styles';
162
- > ```
239
+ Full documentation at 👉 **[opencorestack.github.io/OpenGridX](https://opencorestack.github.io/OpenGridX/)**
163
240
 
164
- ## 📚 Documentation
241
+ ### 🏛️ Components
242
+ - **[DataGrid](docs/components/datagrid.md)** — Main component props and slots
243
+ - **[Toolbar & Pagination](docs/components/toolbar.md)** — Supplemental UI components
165
244
 
166
- Detailed documentation is available in the [docs/](docs/README.md) directory.
167
-
168
- ### 🏛️ Components API
169
- - **[DataGrid](docs/components/datagrid.md)** - Main component props and slots
170
- - **[Header](docs/components/header.md)** - Column headers and grouping
171
- - **[Row & Cell](docs/components/row.md)** - Row and Cell customization
172
- - **[Toolbar & Pagination](docs/components/toolbar.md)** - Supplemental UI components
173
-
174
- ### 🚀 Core Features
175
- - **[Virtualization](docs/features/virtualization.md)** - 60fps rendering for 100k+ rows
176
- - **[Filtering & Search](docs/features/filtering.md)** - Quick filters and advanced operators
177
- - **[Sorting & Pagination](docs/features/sorting-pagination.md)** - Multi-column organization
178
- - **[Editing & Reordering](docs/features/editing-reordering.md)** - Inline edits and Drag-and-Drop
179
- - **[Loading & Performance](docs/features/loading-states.md)** - Skeletons, Lazy, and Infinite loading
180
- - **[Row Selection](docs/features/selection.md)** - Checkbox and multi-row interaction
181
- - **[Pinning](docs/features/pinning.md)** - Sticky columns and rows
182
- - **[State Persistence](docs/features/state-persistence.md)** - Save/Restore grid configuration
183
- - **[Infinite Scroll](docs/features/infinite-scroll.md)** - Seamless lazy-loading
245
+ ### 🚀 Features
246
+ - **[Virtualization](docs/features/virtualization.md)** — 60fps rendering for 100k+ rows
247
+ - **[Filtering & Search](docs/features/filtering.md)** — Quick filters and advanced operators
248
+ - **[Sorting & Pagination](docs/features/sorting-pagination.md)** — Multi-column sorting
249
+ - **[Editing & Reordering](docs/features/editing-reordering.md)** — Inline edits and DnD
250
+ - **[Row Selection](docs/features/selection.md)** — Checkbox and multi-row interaction
251
+ - **[Pinning](docs/features/pinning.md)** — Sticky columns and rows
252
+ - **[State Persistence](docs/features/state-persistence.md)** — Save/Restore grid state
253
+ - **[Infinite Scroll](docs/features/infinite-scroll.md)** — Seamless lazy-loading
254
+ - **[Export Guide](docs/features/export-guide.md)** — Excel, CSV, and Print
255
+ - **[Data Source](docs/features/data-source.md)** — Server-side integration
184
256
 
185
257
  ### 📊 Advanced Data
186
- - **[Aggregation & Pivot](docs/features/aggregation-pivot.md)** - Summary totals and multidimensional data
187
- - **[Tree Data & Grouping](docs/features/tree-data-grouping.md)** - Hierarchical display and Column Grouping
188
- - **[Cell Spanning](docs/features/cell-spanning.md)** - Colspan and Rowspan implementation
189
- - **[Master-Detail](docs/features/master-detail.md)** - Expandable Detail Panels
190
- - **[List View](docs/features/list-view.md)** - Responsive card-based layout
191
- - **[Export Guide](docs/features/export-guide.md)** - Excel, CSV, and Print functionality
192
- - **[Data Source](docs/features/data-source.md)** - Connecting to backend APIs
258
+ - **[Aggregation & Pivot](docs/features/aggregation-pivot.md)** — Summary totals
259
+ - **[Tree Data & Grouping](docs/features/tree-data-grouping.md)** — Hierarchical rows
260
+ - **[Cell Spanning](docs/features/cell-spanning.md)** — Colspan and Rowspan
261
+ - **[Master-Detail](docs/features/master-detail.md)** — Expandable detail panels
193
262
 
194
263
  ### 🎨 Customization
195
- - **[Theming Guide](docs/customization/theming.md)** - Visual styles and CSS variables
196
- - **[Slots API](docs/customization/slots-api.md)** - Component replacement system
197
- - **[Custom Pagination](docs/features/custom-pagination.md)** - Custom paging UI
264
+ - **[Theming Guide](docs/customization/theming.md)** — CSS variables and custom themes
265
+ - **[Slots API](docs/customization/slots-api.md)** — Component replacement system
198
266
 
199
- ## 📊 Development Status
267
+ ---
200
268
 
201
- Currently in **Phase 4: Server-Side Integration**.
202
- All core UI features (Pinning, Spanning, Tree Data, Grouping, Skeleton Loading, Custom Components) are fully implemented and verified in the [demo app](demo/).
269
+ ## 🚀 Why OpenGridX?
270
+
271
+ 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.
203
272
 
204
- ### Recent Updates
205
- - ✅ Skeleton loader with dynamic column calculation
206
- - ✅ Slots system for component customization
207
- - ✅ Fixed horizontal scrolling for wide tables
208
- - ✅ Enhanced empty states
273
+ | Feature | MUI Free | MUI Pro ($$$) | AG Grid Community | **OpenGridX** |
274
+ | :--- | :---: | :---: | :---: | :---: |
275
+ | Virtualization | ✅ | ✅ | ✅ | ✅ |
276
+ | Column Pinning | ❌ | ✅ | ✅ | ✅ |
277
+ | Row Grouping | ❌ | ✅ | ✅ | ✅ |
278
+ | Tree Data | ❌ | ✅ | ✅ | ✅ |
279
+ | Master-Detail | ❌ | ✅ | ✅ | ✅ |
280
+ | Excel Export | ❌ | ✅ | ❌ | ✅ |
281
+ | Advanced Filtering | ❌ | ✅ | ❌ | ✅ |
282
+ | Aggregation | ❌ | ✅ | ❌ | ✅ |
283
+ | Pivot Mode | ❌ | ✅ | ❌ | ✅ |
284
+ | **Price** | Free | **$$$** | Free (limited) | **Free** |
209
285
 
210
286
  ---
211
287
 
212
288
  ## 📝 License
289
+
213
290
  MIT © 2026 Open Core Stack