Skip to content

Commit 230dce4

Browse files
authored
Merge pull request #8 from OpenCoreStack/docs/ai-context-3.10.1
docs: AI context file and README up to 3.10.1
2 parents 2aa1309 + 259f4f4 commit 230dce4

3 files changed

Lines changed: 57 additions & 15 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,8 @@ This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agent
184184
| `cellSelection` | `boolean` | Spreadsheet-style cell range selection; Ctrl/Cmd+C then copies the range (v3.3). |
185185
| `cellSelectionModel` / `onCellSelectionModelChange` | `GridCellSelectionModel` / `(model, { reason }) => void` | Controlled cell range. |
186186
| `showCellSelectionStats` | `boolean` | Status bar with count, sum and average of the range. |
187+
| `undoRedo` | `boolean \| GridUndoRedoOptions` | Undo / redo of edits, paste, range clear and fill (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y); `{ limit }` sets the history size (v3.4). |
188+
| `aiAssistant` | `GridAiAssistantOptions` | Ask AI panel in the toolbar; your `onPrompt` calls your model. Also `onAiAssistantApply` / `onAiAssistantError` (v3.5). See [AI toolkit](docs/features/ai-toolkit.md). |
187189

188190
### Sorting & Filtering
189191

@@ -450,7 +452,7 @@ exportToExcelAdvanced(rows, columns, {
450452
});
451453
exportToJson(rows, columns, { fileName: 'data.json' });
452454
await exportToPdf(rows, columns, { fileName: 'data', title: 'Report Title' });
453-
printGrid(rows, columns, 'Report Title');
455+
await printGrid(rows, columns, 'Report Title');
454456
```
455457

456458
> **Optional peer dependencies:** `exportToExcelAdvanced` requires ExcelJS (`npm install exceljs`); `exportToPdf` requires `npm install jspdf jspdf-autotable`.
@@ -492,20 +494,20 @@ Built-in themes: `darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compac
492494

493495
| Artifact | Size | Gzipped | Notes |
494496
| :--- | :--- | :--- | :--- |
495-
| **What an app ships for `DataGrid`** (your bundler minifies) | 271 KB | **87 KB** | Measured v3.9.0: esbuild, minified, React external, `DataGrid` only |
496-
| **Core ES Module** (`opengridx.es.js`, as published) | 493 KB | 130 KB | Unminified with readable names; use this — tree-shakeable |
497-
| **Core UMD** (`opengridx.umd.js`) | 357 KB | 112 KB | CommonJS / CDN compat |
497+
| **What an app ships for `DataGrid`** (your bundler minifies) | 271 KB | **87 KB** | Measured v3.10.1 (86.6 KB gzipped; CI fails above 92 KB): esbuild, minified, React external, `DataGrid` only |
498+
| **Core ES Module** (`opengridx.es.js`, as published) | 497 KB | 132 KB | Unminified with readable names; use this — tree-shakeable |
499+
| **Core UMD** (`opengridx.umd.js`) | 360 KB | 113 KB | CommonJS / CDN compat |
498500
| **Styles** (`opengridx.css`) | 81 KB | **12 KB** | `import '@opencorestack/opengridx/styles'` |
499501
| **AI toolkit** (`/ai`, optional import) | 20 KB | **7 KB** | Adds nothing unless imported |
500502
| **ExcelJS** (optional peer dep) | — | — | `npm install exceljs` |
501503
| **jsPDF** (optional peer dep) | — | — | `npm install jspdf jspdf-autotable` |
502-
| **npm package download** | — | **~2.5 MB** | Compressed tarball (includes `lib/` source, docs and source maps; 7.8 MB unpacked) |
504+
| **npm package download** | — | **~2.6 MB** | Compressed tarball (includes `lib/` source, docs and source maps; about 8 MB unpacked) |
503505

504506
- **Tree-shaking Ready**: ES Module build — bundlers (Vite, Webpack) only include what you use.
505507
- **Zero UI Dependencies**: No MUI, Ant Design, or Radix. Pure React + vanilla CSS.
506508
- **Lazy Advanced Export**: ExcelJS and jsPDF are optional peer deps — not bundled, loaded only when you call `exportToExcelAdvanced` / `exportToPdf`.
507509
- **Efficient Rendering**: Row and column virtualization keeps the DOM small (needs a bounded grid height): about 19 rows at rest and under 90 while scrolling fast, at 10k or 1M rows.
508-
- **[Benchmarks](docs/performance.md#benchmarks)** (`npm run bench`, Apple M1, Chromium, production build): at 100k rows the grid mounts in 89 ms, sorts in 102–160 ms, filters in 28–33 ms and groups with a sum in 87 ms; at 1M rows mount takes 0.7 s and a sort 1.1–1.3 s. Scrolling missed no frames at any size in Chromium. Past the browser's height cap (645,277 rows at 52 px in Chromium and Safari, about 344,000 in Firefox) rows cannot be scrolled to; page or stream larger datasets.
510+
- **[Benchmarks](docs/performance.md#benchmarks)** (`npm run bench`, Apple M1, Chromium, production build): at 100k rows the grid mounts in 75 ms, sorts in 49–66 ms, filters in 16–20 ms and groups with a sum in 74 ms; at 1M rows mount takes 0.6 s and a sort about 0.47 s. Scrolling stayed under 1 % slow frames at every size in Chromium. At 1M rows a cell edit commits in about 35 ms, select-all takes 60–90 ms and grouping about 190 ms (v3.8–3.10). Past the browser's height cap (645,277 rows at 52 px in Chromium and Safari, about 344,000 in Firefox) rows cannot be scrolled to; page or stream larger datasets.
509511

510512
---
511513

@@ -565,11 +567,11 @@ Most React grids gatekeep essential features like **Row Grouping**, **Excel Expo
565567
| Tree Data | ❌ | ✅ | ✅ | ✅ |
566568
| Master-Detail | ❌ | ✅ | ✅ | ✅ |
567569
| Excel Export | ❌ | ✅ | ❌ | ✅ |
568-
| Advanced Filtering | ❌ | ✅ | ❌ | ✅ |
570+
| Advanced Filtering | ❌ | ✅ | ✅ | ✅ |
569571
| Aggregation | ❌ | ✅ | ❌ | ✅ |
570572
| Pivot Mode | ❌ | ✅ | ❌ | ✅ |
571-
| Inline Cell Editing | ❌ | ✅ | ✅ | ✅ |
572-
| State Persistence | ❌ | ✅ | ❌ | ✅ |
573+
| Inline Cell Editing | ✅ | ✅ | ✅ | ✅ |
574+
| State Persistence | ✅ | ✅ | ❌ | ✅ |
573575
| **Price** | Free | **$$$** | Free (limited) | **Free** |
574576

575577
---
@@ -583,7 +585,7 @@ See [CONTRIBUTING.md](https://github.com/OpenCoreStack/OpenGridX/blob/main/CONTR
583585
```bash
584586
npm test # unit tests (jsdom)
585587
npm run test:browser # real Chromium, Firefox and WebKit
586-
npm run test:smoke # pack the library, install it into React 18/19 apps, run Playwright
588+
npm run test:smoke # pack the library, install it into React 18/19, webpack and Next.js apps, run Playwright
587589
```
588590

589591
Which layer to use, and how the package smoke suite works: [docs/contributing/testing.md](https://github.com/OpenCoreStack/OpenGridX/blob/main/docs/contributing/testing.md).

‎opengridx-ai-context.md‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ that uses the `@opencorestack/opengridx` library. Read it in full before writing
88
## What this library is
99

1010
`@opencorestack/opengridx` is a zero-dependency, high-performance React DataGrid component.
11-
Current version: **3.7.0**. It is a full custom implementation — not a wrapper around MUI or any
11+
Current version: **3.10.1**. It is a full custom implementation — not a wrapper around MUI or any
1212
other library.
1313

1414
---
@@ -331,6 +331,41 @@ apiRef.current.autosizeColumn('name');
331331
apiRef.current.autosizeColumns(); // all columns
332332
```
333333

334+
### Translating the UI: `localeText` (3.9.0+)
335+
336+
```tsx
337+
// Every built-in string is an optional key (about 200); leave one out and the English default is used.
338+
// Some keys are functions of their arguments.
339+
<DataGrid
340+
localeText={{
341+
toolbarSearchPlaceholder: 'Rechercher…',
342+
columnMenuSortAscending: 'Trier par ordre croissant',
343+
aiAssistantChipSort: (field, direction) => `Tri : ${field} (${direction})`, // 3.10.0+
344+
}}
345+
/>
346+
```
347+
348+
Look up key names in the `GridLocaleText` type rather than guessing them. An inline object of strings is fine:
349+
the grid compares it shallowly. Function keys get a new identity on every render, so when you use them, keep
350+
the object stable (a module constant or `useMemo`).
351+
352+
### Theme keys added in 3.9.0
353+
354+
`grid.checkboxCheckedBackground`, `grid.checkboxCheckmark`, `grid.expandIconColor`, `grid.expandIconHoverColor`,
355+
`overlays.itemIndicatorColor`, `overlays.itemSelectedIcon`, `overlays.iconColor`, `overlays.sectionLabelText`,
356+
`overlays.dividerColor`. Each one defaults to the look of earlier versions. The demo's Theme Builder edits them.
357+
358+
### Large datasets (3.8.0–3.10.1)
359+
360+
Edits, paste, fill, undo, select-all and row grouping are fast at 1M rows, with no API change; numbers are in
361+
`docs/performance.md`. To keep them fast:
362+
- **Keep handler props stable** (`useCallback`), as well as `slotProps` and function-valued `localeText` keys. Rows are memoised,
363+
so a prop that changes identity on every render re-renders every visible row.
364+
- **Commit edits through `processRowUpdate`** and return the updated row. The grid then patches only that row
365+
instead of re-processing all of them.
366+
- **Sorting takes about 0.4–0.5 s at 1M rows, and the first quick-filter search about 1.6–2 s.** For larger or
367+
slower data, use server-side sorting and filtering.
368+
334369
---
335370

336371
## v2 → v3 migration (if this project was on v2)
@@ -428,9 +463,11 @@ const hasChildren = params.rowMeta?.hasChildren;
428463
- **Import the stylesheet** — `import '@opencorestack/opengridx/styles'` once in the app root.
429464
- **Next.js App Router: column functions stay in the client file** — render the grid from a `'use client'`
430465
component and pass server-fetched rows as props; `valueFormatter` / `renderCell` cannot be passed from a
431-
Server Component. Install or alias `exceljs` / `jspdf` / `jspdf-autotable` or `next build` fails. See `docs/features/nextjs.md`.
432-
- **Don't pin columns in right-to-left grids** — `dir="rtl"` works for unpinned grids (3.6+), but pinned
433-
columns use physical sticky offsets and scroll away. See `docs/features/rtl.md`.
466+
Server Component. The optional peers `exceljs` / `jspdf` / `jspdf-autotable` are needed only for
467+
`exportToExcelAdvanced` / `exportToPdf`; without them `next build` still succeeds (3.6+, no `next.config` alias).
468+
See `docs/features/nextjs.md`.
469+
- **Right-to-left grids** — `dir="rtl"` works, including pinned columns (3.6+): `pinnedColumns.left` / `right`
470+
mean inline start / end, so in RTL `left` pins to the right edge. See `docs/features/rtl.md`.
434471
- **Controlled props need their callback** — `paginationModel` without `onPaginationModelChange` (or `sortModel`
435472
without `onSortModelChange`) freezes that state. Leave both out to let the grid own it.
436473
- **Give the grid a bounded height** — without a `height` prop the grid fills its container (3.0.1+); in a flex layout wrap it in `<div style={{ flex: 1, minHeight: 0 }}>`.

‎scripts/check-versions.mjs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,13 @@ if (read('demo/public/llms.txt') !== llms) problems.push('demo/public/llms.txt d
1616
const claudeVersion = read('CLAUDE.md').match(/\*\*Current version:\*\* (\S+)/)?.[1];
1717
if (claudeVersion !== version) problems.push(`CLAUDE.md says "Current version: ${claudeVersion}"`);
1818

19+
const contextVersion = read('opengridx-ai-context.md').match(/Current version: \*\*(\S+?)\*\*/)?.[1];
20+
if (contextVersion !== version) problems.push(`opengridx-ai-context.md says "Current version: ${contextVersion}"`);
21+
1922
if (!read('CHANGELOG.md').includes(`## [${version}]`)) problems.push(`CHANGELOG.md has no "## [${version}]" entry`);
2023

2124
if (problems.length > 0) {
2225
console.error(`check:versions: package.json is ${version}, but:\n - ${problems.join('\n - ')}`);
2326
process.exit(1);
2427
}
25-
console.log(`check:versions: ${version} everywhere (llms.txt, demo copy, CLAUDE.md, CHANGELOG)`);
28+
console.log(`check:versions: ${version} everywhere (llms.txt, demo copy, CLAUDE.md, opengridx-ai-context.md, CHANGELOG)`);

0 commit comments

Comments
 (0)