@kanunilabs/datagrid 1.0.0

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/LICENSE +55 -0
  2. package/README.md +243 -0
  3. package/dist/datagrid.umd.js +13 -0
  4. package/dist/index.cjs +2 -0
  5. package/dist/index.d.cts +501 -0
  6. package/dist/index.d.ts +501 -0
  7. package/dist/index.js +2 -0
  8. package/dist/styles.css +3526 -0
  9. package/package.json +77 -0
package/LICENSE ADDED
@@ -0,0 +1,55 @@
1
+ KanuniLabs Community License
2
+ Version 1.0
3
+
4
+ Copyright (c) 2024-present KanuniLabs. All rights reserved.
5
+
6
+ This package (the "Software") is made available free of charge, but it is
7
+ proprietary software and is NOT open source. By installing or using the
8
+ Software you agree to these terms.
9
+
10
+ 1. LICENSE GRANT
11
+ KanuniLabs grants you a worldwide, royalty-free, non-exclusive license to:
12
+ (a) install and use the Software as a dependency of your applications,
13
+ including commercial applications; and
14
+ (b) reproduce and distribute the Software solely as an incorporated,
15
+ compiled part of such applications.
16
+
17
+ 2. RESTRICTIONS
18
+ You may NOT:
19
+ (a) modify, adapt, translate, or create derivative works of the Software;
20
+ (b) decompile, disassemble, deobfuscate, or otherwise attempt to derive
21
+ the source code of the Software, except, and only to the extent,
22
+ applicable law expressly permits notwithstanding this limitation;
23
+ (c) distribute, publish, sublicense, sell, rent, or lease the Software on
24
+ its own, or as part of any toolkit, component, library, or product
25
+ that competes with KanuniLabs products;
26
+ (d) remove, obscure, or alter any copyright, trademark, or other
27
+ proprietary notice.
28
+
29
+ 3. OWNERSHIP
30
+ The Software is licensed, not sold. KanuniLabs retains all right, title,
31
+ and interest in and to the Software, including all intellectual property
32
+ rights. No rights are granted except as expressly stated herein.
33
+
34
+ 4. ENTERPRISE FEATURES
35
+ Certain features require a separate paid license
36
+ (@kanunilabs/pivotgrid-react-enterprise). This license grants no right to
37
+ those features.
38
+
39
+ 5. NO WARRANTY
40
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
41
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
42
+ FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
43
+
44
+ 6. LIMITATION OF LIABILITY
45
+ IN NO EVENT SHALL KANUNILABS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
46
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
47
+ FROM OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
48
+ THE SOFTWARE.
49
+
50
+ 7. TERMINATION
51
+ This license terminates automatically if you breach any term. Upon
52
+ termination you must cease all use and distribution of the Software.
53
+
54
+ For commercial licensing, source access, or other arrangements, contact
55
+ licensing@kanunilabs.com.
package/README.md ADDED
@@ -0,0 +1,243 @@
1
+ <p align="center">
2
+ <a href="https://www.kanunilabs.com"><img src="https://www.kanunilabs.com/logo.png" width="84" alt="KanuniLabs" /></a>
3
+ </p>
4
+
5
+ <h1 align="center">KanuniLabs DataGrid for JavaScript</h1>
6
+
7
+ <p align="center">
8
+ A high-performance data grid with a Web Worker pipeline —<br />
9
+ sort, filter and scroll a million rows without freezing the UI.<br />
10
+ No framework, no JSX, no build step required.
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://www.kanunilabs.com">Website</a> ·
15
+ <a href="https://www.kanunilabs.com/playground/datagrid/javascript">Live Demo</a> ·
16
+ <a href="https://www.kanunilabs.com/docs/datagrid/javascript">Documentation</a> ·
17
+ <a href="https://www.kanunilabs.com/pricing">Pricing</a> ·
18
+ <a href="https://www.kanunilabs.com/contact">Support</a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <a href="https://www.npmjs.com/package/@kanunilabs/datagrid"><img src="https://img.shields.io/npm/v/%40kanunilabs%2Fdatagrid.svg?label=npm" alt="npm version" /></a>
23
+ <img src="https://img.shields.io/badge/TypeScript-included-3178c6.svg" alt="TypeScript types included" />
24
+ <img src="https://img.shields.io/badge/framework-none-f7df1e.svg" alt="No framework required" />
25
+ <img src="https://img.shields.io/badge/license-Community%20(free)-2ea44f.svg" alt="KanuniLabs Community License" />
26
+ </p>
27
+
28
+ <p align="center">
29
+ <a href="https://www.kanunilabs.com/playground/datagrid/javascript">Try it live</a> — a million rows in your browser. No signup, no install.
30
+ </p>
31
+
32
+ ## Why KanuniLabs DataGrid?
33
+
34
+ - **Nothing between you and the DOM** — one call against an element builds the grid. No component tree, no reconciler, no framework version to keep up with. It runs the same in a Vite app, a Rails or Django template, an Electron window, or a plain `<script>` tag on a page.
35
+ - **The same engine the React package uses** — `@kanunilabs/datagrid-core` is a real dependency, not a copy. The renderer differs; the pipeline, the events and the controller API do not.
36
+ - **Worker-backed pipeline** — above ~20,000 rows, filtering and sorting move off the main thread automatically. Columns are encoded once into typed arrays and transferred (zero-copy); a later sort or filter reuses them instead of re-encoding.
37
+ - **Measured, not claimed** — the engine at **1,000,000 rows × 15 columns**, worker path, median of 5 runs: numeric sort **90 ms**, text sort **108 ms**, date sort **123 ms**, two-column sort **192 ms**, equality filter **19 ms**, free-text search **58 ms**. Reproduce them yourself: `node packages/datagrid-core/bench/pipeline.bench.mjs 1000000`.
38
+ - **Typed anyway** — the package ships `.d.ts` files, so an editor autocompletes the config even in a plain `.js` file.
39
+
40
+ ## Quick start
41
+
42
+ ```bash
43
+ npm install @kanunilabs/datagrid
44
+ ```
45
+
46
+ `@kanunilabs/datagrid-core` (the engine) is installed automatically.
47
+
48
+ ```js
49
+ import { createGrid } from '@kanunilabs/datagrid';
50
+ import '@kanunilabs/datagrid/styles.css';
51
+
52
+ const columns = [
53
+ { field: 'id', headerName: 'ID', dataType: 'number', width: 80, pin: 'left' },
54
+ { field: 'product', headerName: 'Product', width: 220 },
55
+ { field: 'region', headerName: 'Region', width: 140 },
56
+ {
57
+ field: 'revenue',
58
+ headerName: 'Revenue',
59
+ dataType: 'number',
60
+ width: 140,
61
+ valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
62
+ },
63
+ ];
64
+
65
+ const grid = createGrid(document.getElementById('grid'), {
66
+ gridId: 'sales',
67
+ dataSource: rows,
68
+ rowKey: 'id',
69
+ columns,
70
+ selection: { mode: 'multiple', checkboxColumn: true },
71
+ sorting: { multi: true },
72
+ filterRow: true,
73
+ headerFilter: true,
74
+ toolbar: true,
75
+ });
76
+ ```
77
+
78
+ The host element owns the size — give it a height in your own CSS. `rowKey` is required: selection, focus and live updates are keyed by row identity, which is what lets them survive sorting and filtering.
79
+
80
+ Three methods carry the lifecycle:
81
+
82
+ ```js
83
+ grid.setData(nextRows); // swap the data, keep scroll, selection and sort
84
+ grid.controller; // the full engine API — 57 typed events, imperative intents
85
+ grid.destroy(); // removes every listener, timer, popup and worker
86
+ ```
87
+
88
+ ### Without a bundler
89
+
90
+ A UMD build ships in the package, so a `<script>` tag is a complete install:
91
+
92
+ ```html
93
+ <link rel="stylesheet" href="https://unpkg.com/@kanunilabs/datagrid/dist/styles.css" />
94
+ <script src="https://unpkg.com/@kanunilabs/datagrid/dist/datagrid.umd.js"></script>
95
+
96
+ <div id="grid" style="height: 600px"></div>
97
+ <script>
98
+ const grid = KanuniLabsDataGrid.createGrid(document.getElementById('grid'), {
99
+ gridId: 'sales',
100
+ dataSource: rows,
101
+ rowKey: 'id',
102
+ columns,
103
+ });
104
+ </script>
105
+ ```
106
+
107
+ The engine is bundled into that file — one request, no import map, nothing to configure.
108
+
109
+ ## The Web Worker: nothing to configure
110
+
111
+ Filtering and sorting run off the main thread above 20,000 rows. The worker is compiled into the package and started from a Blob URL, so there is no file to copy, no bundler recipe, and nothing to import — Vite, webpack, Next.js and Parcel all just work, and so does no bundler at all.
112
+
113
+ Set `worker: { enabled: false }` to stay on the main thread entirely, or `worker: { threshold: 50_000 }` to change when the offload kicks in.
114
+
115
+ **Strict Content-Security-Policy.** A Blob worker needs `worker-src 'self' blob:`. If your CSP forbids it, either allow it or serve the worker as a file instead — `datagrid.worker.js` ships in `@kanunilabs/datagrid-core` either way:
116
+
117
+ ```js
118
+ createGrid(host, { worker: { url: '/vendor/datagrid.worker.js' }, /* ... */ });
119
+ ```
120
+
121
+ ## Excel export (optional)
122
+
123
+ CSV export needs nothing extra. For `.xlsx`, install the optional peer:
124
+
125
+ ```bash
126
+ npm i exceljs
127
+ ```
128
+
129
+ Without it, CSV export still works and the Excel path reports an actionable error instead of failing at import time.
130
+
131
+ ## Theming
132
+
133
+ Six themes × six palettes, light and dark, driven by config or by CSS custom properties on the host:
134
+
135
+ ```js
136
+ createGrid(host, { theme: 'material', palette: 'indigo', density: 'compact', dark: true, /* ... */ });
137
+ ```
138
+
139
+ Full token list and the caveats (portalled popups, row height and the virtualizer) are in the [theming guide](https://www.kanunilabs.com/docs/datagrid/theming).
140
+
141
+ ## Coming from the React package?
142
+
143
+ The config mirrors the React props by name, so most of a `<DataGrid>` reads across unchanged. The handful of names that differ are the DOM-flavoured ones, and the grid **tells you** rather than ignoring them — pass a React-only spelling and it warns in the console with the correct one:
144
+
145
+ | React prop | JavaScript config |
146
+ |---|---|
147
+ | `columnResize` | `resizable` |
148
+ | `columnReorder` | `reorderable` |
149
+ | `groupPanel` | `grouping: { panel: true }` |
150
+ | `onReady` | the controller is returned — `grid.controller` |
151
+ | `className` / `style` | style the host element you pass in |
152
+
153
+ Anything React-valued — `renderCell` returning JSX, a React element as an icon — has no equivalent here by nature; give it a string, or reach for the React package.
154
+
155
+ ## Enterprise edition
156
+
157
+ Community is a complete grid: a million rows, sorting, filtering, selection,
158
+ pagination, grouping, themes, twelve languages and CSV export. Nothing here is
159
+ a trial and nothing expires.
160
+
161
+ `@kanunilabs/datagrid-enterprise` starts where you **change** the data and where
162
+ you **take it out** — editing, range selection and the fill handle, server-side
163
+ data, Excel and PDF export, charts. `createEnterpriseGrid` is a drop-in
164
+ replacement for `createGrid`: same config, plus those.
165
+
166
+ ```bash
167
+ # Ships from our private registry; a license includes the credentials.
168
+ npm i @kanunilabs/datagrid-enterprise
169
+ ```
170
+
171
+ ```js
172
+ import { createEnterpriseGrid } from '@kanunilabs/datagrid-enterprise';
173
+
174
+ const grid = createEnterpriseGrid(host, {
175
+ licenseKey: 'KLAB1....',
176
+ dataSource: rows,
177
+ rowKey: 'id',
178
+ columns,
179
+ editing: { mode: 'cell' },
180
+ });
181
+ ```
182
+
183
+ Without a key the grid still runs — watermarked, not crippled — so an
184
+ evaluation or a stale staging key never takes an application down.
185
+
186
+ **One license opens both products**, DataGrid and
187
+ [PivotGrid](https://www.npmjs.com/package/@kanunilabs/pivotgrid-react).
188
+
189
+ - [Enterprise & licensing](https://www.kanunilabs.com/docs/datagrid/enterprise)
190
+ - [Private registry access](https://www.kanunilabs.com/docs/datagrid/registry)
191
+ - [Pricing](https://www.kanunilabs.com/pricing)
192
+
193
+ ## Feature overview
194
+
195
+ | | Community (this package) | Enterprise |
196
+ |---|:---:|:---:|
197
+ | Virtualized rows + columns · 1M rows | ✅ | ✅ |
198
+ | Worker offload + columnar encoding | ✅ | ✅ |
199
+ | Sorting · resize · reorder · pinning · bands | ✅ | ✅ |
200
+ | Filter row · header filter popup · search | ✅ | ✅ |
201
+ | Row/cell selection · checkbox · focused row | ✅ | ✅ |
202
+ | Keyboard navigation + WAI-ARIA grid | ✅ | ✅ |
203
+ | Grouping (one level) + group panel | ✅ | ✅ |
204
+ | Pagination · infinite scroll · toolbar · column chooser | ✅ | ✅ |
205
+ | 6 themes × 6 palettes · dark mode · 12 locales | ✅ | ✅ |
206
+ | 57 events + imperative controller API | ✅ | ✅ |
207
+ | Saved views · tooltips · row numbers · print | ✅ | ✅ |
208
+ | **CSV** export & import | ✅ | ✅ |
209
+ | **UMD build** — works from a `<script>` tag | ✅ | ✅ |
210
+ | **Editing** — cell, row, form + validation & undo | — | ✅ |
211
+ | Range selection · fill handle · cut & paste | — | ✅ |
212
+ | Multi-level grouping · group totals · footer totals | — | ✅ |
213
+ | Master-detail · tree data · cell spans · notes | — | ✅ |
214
+ | **Server-side data** (filter/sort/page/totals remote) | — | ✅ |
215
+ | **Excel** & **PDF** export (styled, paginated) | — | ✅ |
216
+ | Chart panel · sparklines · cross-filter | — | ✅ |
217
+ | Nested filter builder · import wizard | — | ✅ |
218
+ | Side bar · status bar | — | ✅ |
219
+
220
+ Full breakdown, with a link to the guide for each line:
221
+ [Enterprise & licensing](https://www.kanunilabs.com/docs/datagrid/enterprise).
222
+
223
+ ## Documentation
224
+
225
+ - [JavaScript guide](https://www.kanunilabs.com/docs/datagrid/javascript)
226
+ - [Getting started](https://www.kanunilabs.com/docs/datagrid)
227
+ - [Installation](https://www.kanunilabs.com/docs/datagrid/installation)
228
+ - [Features](https://www.kanunilabs.com/docs/datagrid/features)
229
+ - [Theming](https://www.kanunilabs.com/docs/datagrid/theming)
230
+ - [Performance](https://www.kanunilabs.com/docs/datagrid/performance)
231
+ - [Live playground](https://www.kanunilabs.com/playground/datagrid/javascript)
232
+
233
+ ## Missing a feature? Tell us
234
+
235
+ This grid is actively developed and shaped by the people using it. If something is missing, awkward, or broken, we want to hear about it — feature requests and bug reports go to the same place and get read by the people who write the code:
236
+
237
+ **[Send us your feedback →](https://www.kanunilabs.com/contact)**
238
+
239
+ ## License
240
+
241
+ Free to use under the KanuniLabs Community License (proprietary, source not distributed). See the `LICENSE` file in the package.
242
+
243
+ © KanuniLabs · [kanunilabs.com](https://www.kanunilabs.com)