|
| 1 | +# OpenGridX Project Context |
| 2 | + |
| 3 | +## 🌟 Project Overview |
| 4 | +**OpenGridX** (`@opencorestack/opengridx`) is a zero-dependency, high-performance DataGrid library for React, engineered to match and extend the feature set of MUI X DataGrid Pro — offered completely free. |
| 5 | +- **npm**: `@opencorestack/opengridx` (published under the `opencorestack` npm org, owned by `asif7774`) |
| 6 | +- **Project Path**: `/Volumes/Data/RND/OpenGridX` |
| 7 | +- **Core Value**: 100% custom implementation with ZERO external UI dependencies (no MUI, no Emotion, no Tailwind). |
| 8 | +- **Performance**: Handles 100,000+ rows via custom virtualization at 60fps. |
| 9 | +- **Current Version**: `0.1.3` (published to npm) |
| 10 | + |
| 11 | +## 📦 NPM Publication Status |
| 12 | +- **v0.1.0** → Published ✅ (March 6, 2026 — first publish) |
| 13 | +- **v0.1.1** → Published ✅ (March 6, 2026 — ExcelJS externalized, cleaned devDeps, improved README) |
| 14 | +- **v0.1.2** → Published ✅ (March 6, 2026 — Cell editing internal state bug fix) |
| 15 | +- **v0.1.3** → Published ✅ (March 10, 2026 — CSS auto-import fix via barrel entry) |
| 16 | +- **Package URL**: https://www.npmjs.com/package/@opencorestack/opengridx |
| 17 | +- **npm org**: `opencorestack` (owner: `asif7774`) |
| 18 | +- **Next publish**: bump version in `package.json`, then `npm publish --access public --otp=<code>` |
| 19 | + |
| 20 | +### 🚨 VERSION BUMPING RULE |
| 21 | +Whenever you increment the version in `package.json`, you **MUST ALSO** update it in: |
| 22 | +1. `CHANGELOG.md` |
| 23 | +2. `llms.txt` |
| 24 | +3. `demo/public/llms.txt` (via `cp` from root) |
| 25 | +4. `demo/App.tsx` (sidebar `<span className="app-version">`) |
| 26 | +5. `demo/Home.tsx` (hero section `<span className="home-badge">`) |
| 27 | +Always keep the demo and AI context files fully in sync with the NPM package version! |
| 28 | + |
| 29 | +## 🏗️ Architecture & Technology Stack |
| 30 | +- **Framework**: React 18+ with strict TypeScript 5+ |
| 31 | +- **State Management**: `useReducer` / `useContext` internally, exposed via `apiRef` pattern |
| 32 | +- **Styling**: Vanilla CSS using BEM methodology (`ogx__` prefix, `--ogx-*` CSS variables) |
| 33 | +- **Build**: Vite + `vite-plugin-dts` → outputs ES Module + UMD + CSS + TypeScript declarations |
| 34 | +- **Entry point**: `lib/index.ts` → `dist/opengridx.es.js` + `dist/opengridx.umd.js` |
| 35 | + |
| 36 | +## 📂 Directory Structure |
| 37 | +- `lib/` — Core library source (published via `dist/`) |
| 38 | + - `lib/components/` — React components (DataGrid, Row, Cell, Header, Toolbar, etc.) |
| 39 | + - `lib/hooks/` — Feature hooks (useGridClipboard, useAggregation, usePivot, etc.) |
| 40 | + - `lib/utils/export/` — CSV, Excel, ExcelAdvanced, JSON, Print utilities |
| 41 | + - `lib/styles/` — All CSS (barrel: `opengridx.css`) |
| 42 | + - `lib/types/` — Full TypeScript types (`GridApi`, `GridColDef`, `DataGridProps`, etc.) |
| 43 | + - `lib/theme/` — `DataGridThemeProvider` + 5 built-in themes |
| 44 | + - `lib/state/` — `useGridStateStorage` + `initialState` support |
| 45 | + - `lib/index.ts` — Public barrel exports |
| 46 | +- `demo/` — Interactive showcase app (Vite dev server, port 5173) |
| 47 | + - `demo/pages/` — Installation, Quickstart, API docs pages |
| 48 | + - `demo/examples/` — ~30 feature demos |
| 49 | + - `demo/public/llms.txt` — AI-readable package description |
| 50 | +- `docs/` — Markdown documentation (features, components, customization) |
| 51 | +- `.agent/` — Project context and workflow definitions |
| 52 | +- `vite.config.lib.js` — Library build config |
| 53 | +- `vite.config.js` — Demo app build config |
| 54 | + |
| 55 | +## 🔑 Key Build Configuration (vite.config.lib.js) |
| 56 | +```js |
| 57 | +external: ['react', 'react-dom', 'exceljs'] // ExcelJS is peer dep, NOT bundled |
| 58 | +sourcemap: true |
| 59 | +formats: ['es', 'umd'] |
| 60 | +``` |
| 61 | + |
| 62 | +## 📦 Package Dependencies |
| 63 | +```json |
| 64 | +"peerDependencies": { "react": ">=18.0.0", "react-dom": ">=18.0.0", "exceljs": ">=4.0.0" } |
| 65 | +"peerDependenciesMeta": { "exceljs": { "optional": true } } |
| 66 | +"dependencies": {} |
| 67 | +``` |
| 68 | + |
| 69 | +## ✅ v0.1.1 Feature-Complete List |
| 70 | +- High-Performance Row + Column Virtualization (60fps, 100k+ rows) |
| 71 | +- Multi-Column Sorting (client + server-side) |
| 72 | +- Advanced Filtering (11+ operators, AND/OR filter builder) |
| 73 | +- Pagination (client + server + infinite scroll) |
| 74 | +- Row Selection (checkbox, single/multi, controlled/uncontrolled) |
| 75 | +- Column Pinning (left/right sticky) |
| 76 | +- Row Pinning (top/bottom) |
| 77 | +- Column Resizing (throttled 60fps drag) |
| 78 | +- Column & Row Reordering (DnD) |
| 79 | +- Detail Panels (master-detail) |
| 80 | +- Cell & Row Spanning (colSpan/rowSpan) |
| 81 | +- List View Mode (card-based layout) |
| 82 | +- Column Grouping (multi-level headers) |
| 83 | +- Toolbar (built-in + replaceable via slots) |
| 84 | +- Inline Cell Editing |
| 85 | +- Tree Data (hierarchical rows, lazy server-side children) |
| 86 | +- Row Grouping (collapsible, with aggregation) |
| 87 | +- Aggregation (SUM, AVG, COUNT, MIN, MAX) |
| 88 | +- Pivot Mode (multidimensional) |
| 89 | +- CSV / JSON / Print Export (zero deps) |
| 90 | +- Basic Excel Export (`exportToExcel` — HTML-based, zero deps) |
| 91 | +- Advanced Excel Export (`exportToExcelAdvanced` — real .xlsx binary, requires `exceljs`) |
| 92 | +- Clipboard: Ctrl+C / Cmd+C → TSV for Excel/Sheets |
| 93 | +- Clipboard: Programmatic `apiRef.current.copySelectedRows()` |
| 94 | +- DataGridThemeProvider + 5 built-in themes |
| 95 | +- CSS Variables (`--ogx-*` prefix), Shadow DOM compatible |
| 96 | +- WCAG 2.1 AA Accessibility (ARIA roles, keyboard navigation) |
| 97 | +- State Persistence (`initialState` prop + `useGridStateStorage` hook) |
| 98 | +- `apiRef` imperative API (getSelectedRows, copySelectedRows, selectRow, setFilterModel, etc.) |
| 99 | +- Slots system (replace any internal component) |
| 100 | +- Skeleton Loader (animated, auto-detects columns) |
| 101 | +- Server-side data source (`useGridDataSource` hook) |
| 102 | + |
| 103 | +## 🔧 Recent Fixes (v0.1.1) |
| 104 | +- `Ctrl+C` now works when grid checkboxes are focused |
| 105 | +- Programmatic `apiRef.current.copySelectedRows()` correctly reads live selection |
| 106 | +- ExcelJS moved from `dependencies` → optional `peerDependencies` AND marked `external` in Vite |
| 107 | +- `getSelectedRows()` on apiRef returns live selection state (was returning stale data) |
| 108 | +- `copySelectedRows` placeholder added to initial apiRef in `useDataGrid.ts` to satisfy `GridApi` type |
| 109 | + |
| 110 | +## 🧠 Key Technical Gotchas |
| 111 | +- **Sticky positioning**: Parent must have `position: relative` + correct overflow settings |
| 112 | +- **ExcelJS**: Is a peer dep AND external in Vite — consumers must `npm install exceljs` separately |
| 113 | +- **CSS auto-import**: `DataGrid.tsx` line 26 imports `opengridx.css` — consumers do NOT need a manual CSS import |
| 114 | +- **apiRef initialization**: Any method added to `GridApi` interface must also have a placeholder in `useDataGrid.ts`'s initial `useRef` object, otherwise the build fails |
| 115 | +- **selectedRowIds**: Must be memoized from `rowSelectionModel` BEFORE calling `useGridClipboard` |
| 116 | +- **Skeleton Columns**: Use `state.dimensions.viewportWidth` not `layout.viewportWidth` |
| 117 | +- **Scrollbar**: Use `scrollbar-gutter: stable` to prevent 15px layout shift on data change |
| 118 | + |
| 119 | +## 🗺️ Roadmap (Post v0.1.1) |
| 120 | +- **v0.2.0 planned**: |
| 121 | + - Rich Excel Styling (bold headers, background fill, native ExcelJS borders) |
| 122 | + - Cell Range Clipboard (select rectangular region, paste from Excel into editable cells) |
| 123 | + - Storybook integration (stories exist in `src/stories/`, Storybook removed from devDeps temporarily) |
| 124 | + |
| 125 | +## 📝 Maintenance Workflows |
| 126 | +- `/dev-demo` — Start demo dev server |
| 127 | +- `/add-feature` — Implementation checklist for new features |
| 128 | +- `/summarize-work` — EOD documentation protocol |
| 129 | + |
| 130 | +## ⚠️ Moved Folder Note |
| 131 | +If the project path has changed from `/Volumes/Data/RND/Custom-DataGrid`, update all path references accordingly. The workspace URI will reflect the new location. |
0 commit comments