@pablovsouza/react-datagrid 0.0.0-stage → 0.1.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.
- package/LICENSE +21 -0
- package/README.md +267 -2
- package/dist/DataGrid.d.ts +11 -0
- package/dist/DataGrid.d.ts.map +1 -0
- package/dist/DataGrid.js +782 -0
- package/dist/DefaultEditor.d.ts +13 -0
- package/dist/DefaultEditor.d.ts.map +1 -0
- package/dist/DefaultEditor.js +59 -0
- package/dist/clipboard.d.ts +5 -0
- package/dist/clipboard.d.ts.map +1 -0
- package/dist/clipboard.js +51 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/keyboard.d.ts +30 -0
- package/dist/keyboard.d.ts.map +1 -0
- package/dist/keyboard.js +53 -0
- package/dist/selection.d.ts +23 -0
- package/dist/selection.d.ts.map +1 -0
- package/dist/selection.js +43 -0
- package/dist/styles.css +256 -0
- package/dist/types.d.ts +198 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +1 -0
- package/package.json +73 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pablo Souza
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,268 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @pablovsouza/react-datagrid
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Keyboard-first data grid for React that behaves like a desktop grid (WinForms `DataGridView`, WPF `DataGrid`):
|
|
4
|
+
|
|
5
|
+
- Virtualized rows: tens of thousands of rows, only the visible ones in the DOM
|
|
6
|
+
- Columns: width, min / max, resize (drag the header edge), reorder (drag the header), hide, freeze at the start
|
|
7
|
+
or the end, alignment, value formatting, flexible width
|
|
8
|
+
- Sorting: click a header (ascending, descending, none), Shift+click for several columns, custom comparators,
|
|
9
|
+
or server-side (`manualSorting`)
|
|
10
|
+
- Row selection (default) or cell selection, with ranges: Shift+arrows, Shift+click, mouse drag, Ctrl+click,
|
|
11
|
+
Ctrl+A
|
|
12
|
+
- Clipboard: Ctrl+C copies the selection as tab-separated text (pastes into Excel, LibreOffice, Google Sheets);
|
|
13
|
+
Ctrl+V pastes into editable cells (one value fills the selection)
|
|
14
|
+
- In-place editing: F2, double-click or typing starts; Enter / Tab commit and move; Esc cancels; editor slots per
|
|
15
|
+
column; commit / cancel events with validation
|
|
16
|
+
- Theming by CSS variables; ARIA `grid` roles; touch (tap, long press, native swipe scrolling)
|
|
17
|
+
|
|
18
|
+
Status: `0.1.0`, developed against a real ERP (SAPE). Not published yet.
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install @pablovsouza/react-datagrid
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Peer dependencies: `react@^19`, `react-dom@^19`. The package ships ES modules for bundlers (Vite, webpack,
|
|
27
|
+
Next.js) and its own stylesheet, imported by the entry (no Tailwind or other setup in the app).
|
|
28
|
+
|
|
29
|
+
## Quick start
|
|
30
|
+
|
|
31
|
+
```tsx
|
|
32
|
+
import { DataGrid, type DataGridColumn } from '@pablovsouza/react-datagrid'
|
|
33
|
+
|
|
34
|
+
interface Product {
|
|
35
|
+
id: number
|
|
36
|
+
name: string
|
|
37
|
+
stock: number
|
|
38
|
+
price: number
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const money = new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })
|
|
42
|
+
|
|
43
|
+
const columns: DataGridColumn<Product>[] = [
|
|
44
|
+
{ id: 'id', header: 'Code', width: 80, align: 'end', frozen: 'start' },
|
|
45
|
+
{ id: 'name', header: 'Name', width: 260, grow: 1, editable: true },
|
|
46
|
+
{ id: 'stock', header: 'Stock', width: 90, align: 'end' },
|
|
47
|
+
{
|
|
48
|
+
id: 'price',
|
|
49
|
+
header: 'Price',
|
|
50
|
+
width: 120,
|
|
51
|
+
align: 'end',
|
|
52
|
+
format: (value) => money.format(value as number)
|
|
53
|
+
}
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
export function Products({ rows }: { rows: Product[] }) {
|
|
57
|
+
return (
|
|
58
|
+
<DataGrid
|
|
59
|
+
rows={rows}
|
|
60
|
+
columns={columns}
|
|
61
|
+
getRowId={(row) => String(row.id)}
|
|
62
|
+
onRowActivate={(row) => open(row)}
|
|
63
|
+
aria-label="Products"
|
|
64
|
+
style={{ height: 400 }}
|
|
65
|
+
/>
|
|
66
|
+
)
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The grid fills the height you give it (`style`, `className`, or a flex parent) and scrolls inside.
|
|
71
|
+
|
|
72
|
+
## Why TanStack Table and TanStack Virtual inside
|
|
73
|
+
|
|
74
|
+
Writing a grid from scratch means re-solving virtualization (scroll anchoring, overscan, `scrollToIndex` with
|
|
75
|
+
sticky headers) and the column model (ordering with hidden and pinned columns, sizing, multi-column sorting).
|
|
76
|
+
Two mature MIT libraries already do exactly that, headless, with no markup or styles of their own:
|
|
77
|
+
|
|
78
|
+
- **[TanStack Table](https://tanstack.com/table)** (v9): sorted row model, column order, sizing, visibility and
|
|
79
|
+
pinning. The grid owns the state (controlled or not) and feeds it in.
|
|
80
|
+
- **[TanStack Virtual](https://tanstack.com/virtual)** (v3): row virtualization.
|
|
81
|
+
|
|
82
|
+
What they do not give, this package adds: the desktop keyboard model, the current cell, row / cell selection with
|
|
83
|
+
ranges, clipboard, in-place editing, mouse and touch gestures, ARIA, theming. Full grids were considered and
|
|
84
|
+
rejected: AG Grid (the useful parts — range selection, clipboard — are in the paid Enterprise edition), MUI X
|
|
85
|
+
Data Grid (same: Pro / Premium, plus Material UI), Glide Data Grid (canvas: no DOM cells for custom React
|
|
86
|
+
content, harder ARIA), react-data-grid (closest fit, MIT, but its keyboard and selection model is not a desktop
|
|
87
|
+
grid's and cell ranges are not built in). Wrapping headless engines keeps the behaviour ours and the hard generic
|
|
88
|
+
parts maintained by others.
|
|
89
|
+
|
|
90
|
+
## Columns
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
interface DataGridColumn<T> {
|
|
94
|
+
id: string // unique, stable (state, sorting, events)
|
|
95
|
+
header: ReactNode
|
|
96
|
+
value?: (row: T) => unknown // default row[id]; used by sort, copy, paste, default cell
|
|
97
|
+
format?: (value: unknown, row: T) => string // shown and copied text
|
|
98
|
+
cell?: (context: CellContext<T>) => ReactNode // custom content
|
|
99
|
+
width?: number // default 150
|
|
100
|
+
minWidth?: number // default 40
|
|
101
|
+
maxWidth?: number
|
|
102
|
+
grow?: number // share of extra width (flex-grow)
|
|
103
|
+
align?: 'start' | 'center' | 'end'
|
|
104
|
+
sortable?: boolean // default true
|
|
105
|
+
resizable?: boolean // default true
|
|
106
|
+
reorderable?: boolean // default true
|
|
107
|
+
hideable?: boolean // default true
|
|
108
|
+
hidden?: boolean // initial
|
|
109
|
+
frozen?: 'start' | 'end' // initial
|
|
110
|
+
compare?: (a: unknown, b: unknown) => number // ascending; default: numbers, dates, natural text
|
|
111
|
+
editable?: boolean | ((row: T) => boolean)
|
|
112
|
+
editor?: (props: EditorProps<T>) => ReactNode // default: text input
|
|
113
|
+
parse?: (text: string, row: T) => unknown // typed / pasted text to value; undefined rejects
|
|
114
|
+
title?: string // header tooltip
|
|
115
|
+
headerClassName?: string
|
|
116
|
+
cellClassName?: string | ((row: T) => string | undefined)
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`CellContext<T>`: `{ row, rowIndex, rowId, column, value, text, selected, active }`.
|
|
121
|
+
|
|
122
|
+
## Props
|
|
123
|
+
|
|
124
|
+
| Prop | Type | Default | |
|
|
125
|
+
| ------------------------------------------------------------------ | ------------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------- |
|
|
126
|
+
| `rows` | `readonly T[]` | | Keep the array stable between renders. |
|
|
127
|
+
| `columns` | `readonly DataGridColumn<T>[]` | | Keep stable (module scope or `useMemo`). |
|
|
128
|
+
| `getRowId` | `(row, index) => string` | | |
|
|
129
|
+
| `selectionMode` | `'row' \| 'cell'` | `'row'` | |
|
|
130
|
+
| `multiSelect` | `boolean` | `true` | Ranges, Ctrl+click, Ctrl+A. |
|
|
131
|
+
| `activeCell` / `defaultActiveCell` / `onActiveCellChange` | `CellPosition \| null` | first cell | Controlled or not. |
|
|
132
|
+
| `activeRowIndex` / `onActiveRowChange` | `number` | | Row-mode shortcut for the current row (`-1`: none). |
|
|
133
|
+
| `selection` / `defaultSelection` / `onSelectionChange` | `CellRange[]` | | The ranges always contain the current cell. |
|
|
134
|
+
| `sorting` / `defaultSorting` / `onSortingChange` | `SortItem[]` | `[]` | `{ columnId, direction }`. |
|
|
135
|
+
| `manualSorting` | `boolean` | `false` | Rows come sorted (server side). |
|
|
136
|
+
| `columnState` / `defaultColumnState` / `onColumnStateChange` | `ColumnState` | from columns | `{ order, widths, hidden, frozenStart, frozenEnd }`: persist it to remember a user's layout. |
|
|
137
|
+
| `rowHeight` / `headerHeight` | `number` | `32` / row height | Pixels. |
|
|
138
|
+
| `overscan` | `number` | `8` | Rows rendered beyond the visible ones. |
|
|
139
|
+
| `editable` | `boolean` | `false` | Turns on editing and paste for `editable` columns. |
|
|
140
|
+
| `onCellEdit` | `(change) => void \| false` | | `false` keeps the editor open. |
|
|
141
|
+
| `onPaste` | `(changes) => void` | one `onCellEdit` per cell | |
|
|
142
|
+
| `onRowActivate` | `(row, rowIndex) => void` | | Enter and double-click (on cells that are not edited). |
|
|
143
|
+
| `onCellContextMenu` | `(cell, row, point) => void` | | Right-click and long press. |
|
|
144
|
+
| `onKeyDown` | `(event, context) => void` | | Runs first; `event.preventDefault()` stops the grid handling the key. |
|
|
145
|
+
| `tabBehavior` | `'cell' \| 'leave'` | `cell` mode: `'cell'`, row mode: `'leave'` | |
|
|
146
|
+
| `rowClassName` | `(row, rowIndex) => string` | | |
|
|
147
|
+
| `empty` | `ReactNode` | | Shown without rows. |
|
|
148
|
+
| `aria-label`, `aria-labelledby`, `className`, `style`, `autoFocus` | | | |
|
|
149
|
+
|
|
150
|
+
`CellChange<T>`: `{ row, rowIndex, rowId, columnId, value, previousValue }`. Row indexes are positions in the
|
|
151
|
+
displayed (sorted) rows.
|
|
152
|
+
|
|
153
|
+
## Handle (`ref`)
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
const grid = useRef<DataGridHandle>(null)
|
|
157
|
+
grid.current.focus()
|
|
158
|
+
grid.current.scrollToRow(500)
|
|
159
|
+
grid.current.getActiveCell() // { row, col } | null
|
|
160
|
+
grid.current.setActiveCell({ row: 0, col: 2 })
|
|
161
|
+
grid.current.selectAll()
|
|
162
|
+
grid.current.getSelectionText() // what Ctrl+C copies
|
|
163
|
+
grid.current.paste('a\tb\n1\t2') // what Ctrl+V does
|
|
164
|
+
grid.current.startEdit()
|
|
165
|
+
grid.current.getDisplayedRows()
|
|
166
|
+
grid.current.getColumnState()
|
|
167
|
+
grid.current.moveColumn('price', 0)
|
|
168
|
+
grid.current.setColumnWidth('name', 300) // null: back to the column's width
|
|
169
|
+
grid.current.setColumnHidden('stock', true)
|
|
170
|
+
grid.current.setColumnFrozen('id', 'start') // or 'end', null
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Keyboard
|
|
174
|
+
|
|
175
|
+
| Key | Row mode | Cell mode |
|
|
176
|
+
| ------------------------ | ------------------------------------------ | ------------------------------------------------------- |
|
|
177
|
+
| ↑ ↓ | previous / next row | cell above / below |
|
|
178
|
+
| ← → | current column (scrolls sideways) | cell left / right |
|
|
179
|
+
| Ctrl+arrow | first / last row or column | edge of the grid in that direction |
|
|
180
|
+
| Home / End | first / last row | first / last cell of the row |
|
|
181
|
+
| Ctrl+Home / Ctrl+End | first / last row | first / last cell of the grid |
|
|
182
|
+
| PageUp / PageDown | one page of rows | one page of rows |
|
|
183
|
+
| Shift + any of the above | extends the range | extends the range |
|
|
184
|
+
| Tab / Shift+Tab | leaves the grid (`tabBehavior`) | next / previous cell, wrapping rows; leaves at the ends |
|
|
185
|
+
| Enter / Shift+Enter | `onRowActivate`; else (editable) down / up | the same |
|
|
186
|
+
| F2 / typing | edits the current cell (editable columns) | the same |
|
|
187
|
+
| Esc | collapses a range; else not handled | the same |
|
|
188
|
+
| Ctrl+A | selects all | selects all |
|
|
189
|
+
| Ctrl+C / Ctrl+V | copies / pastes | copies / pastes |
|
|
190
|
+
|
|
191
|
+
While editing (default editor): Enter / Shift+Enter commit and move down / up, Tab / Shift+Tab commit and move
|
|
192
|
+
right / left, Esc cancels, leaving the cell commits. Custom editors call `commit(value, move)` and `cancel()`;
|
|
193
|
+
the slot cancels on Esc unless the editor called `preventDefault()` (an open dropdown, say).
|
|
194
|
+
|
|
195
|
+
Keys the grid does not use (F-keys, Insert, Delete, Space, Esc with nothing to collapse…) bubble normally, so
|
|
196
|
+
window or app shortcuts keep working. Keys it handles are stopped (`preventDefault` + `stopPropagation`).
|
|
197
|
+
Ctrl means Cmd on macOS.
|
|
198
|
+
|
|
199
|
+
## Mouse and touch
|
|
200
|
+
|
|
201
|
+
Click selects (Shift extends, Ctrl / Cmd adds a range), dragging across cells selects a range, double-click edits
|
|
202
|
+
or activates, right-click calls `onCellContextMenu`. Header click sorts, dragging a header onto another moves it
|
|
203
|
+
there, dragging the header edge resizes and double-clicking it restores the width. On touch screens a tap
|
|
204
|
+
selects, a long press (550 ms) calls `onCellContextMenu`, and scrolling is the browser's own (both axes).
|
|
205
|
+
|
|
206
|
+
## Theming
|
|
207
|
+
|
|
208
|
+
Set the variables on `.rdg`, a parent or `:root`:
|
|
209
|
+
|
|
210
|
+
| Variable | Default | |
|
|
211
|
+
| ---------------------------------------------------------- | ----------------------------- | ------------------------------------------ |
|
|
212
|
+
| `--rdg-bg`, `--rdg-fg` | `Canvas`, `CanvasText` | Grid colours. |
|
|
213
|
+
| `--rdg-border` | 14% text colour | Row and header lines. |
|
|
214
|
+
| `--rdg-header-bg`, `--rdg-header-fg` | | |
|
|
215
|
+
| `--rdg-row-odd-bg`, `--rdg-row-hover-bg` | | Striping, hover. |
|
|
216
|
+
| `--rdg-selected-bg`, `--rdg-selected-fg` | `Highlight`, `HighlightText` | Selected rows. |
|
|
217
|
+
| `--rdg-selected-bg-inactive`, `--rdg-selected-fg-inactive` | the same | Selected rows while the grid has no focus. |
|
|
218
|
+
| `--rdg-range-bg`, `--rdg-range-fg` | 22% selection colour, inherit | Cell mode ranges. |
|
|
219
|
+
| `--rdg-active-outline` | selection colour | Current cell (cell mode). |
|
|
220
|
+
| `--rdg-editor-bg`, `--rdg-editor-fg`, `--rdg-invalid` | | Editor. |
|
|
221
|
+
| `--rdg-font-size`, `--rdg-cell-padding` | inherit, `0 8px` | |
|
|
222
|
+
|
|
223
|
+
Mapping an app's theme, e.g. one with its own selection variables:
|
|
224
|
+
|
|
225
|
+
```css
|
|
226
|
+
.rdg {
|
|
227
|
+
--rdg-bg: var(--background);
|
|
228
|
+
--rdg-fg: var(--foreground);
|
|
229
|
+
--rdg-border: var(--border);
|
|
230
|
+
--rdg-selected-bg: var(--app-selected-bg);
|
|
231
|
+
--rdg-selected-fg: var(--app-selected-fg);
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
The base styles are in the CSS layer `rdg`. Unlayered app CSS always overrides them; an app that uses layers
|
|
236
|
+
(Tailwind v4 does) declares `rdg` first so its utilities win too:
|
|
237
|
+
|
|
238
|
+
```css
|
|
239
|
+
@layer rdg;
|
|
240
|
+
@import 'tailwindcss';
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
The selected-row text colour
|
|
244
|
+
is deliberately unlayered: whatever colour a cell sets for itself (status colours, utility classes such as
|
|
245
|
+
Tailwind's `text-*`), selected text takes `--rdg-selected-fg` and never disappears into the selection
|
|
246
|
+
background. Change the colour through the variables.
|
|
247
|
+
|
|
248
|
+
## Accessibility
|
|
249
|
+
|
|
250
|
+
`role="grid"` with `aria-rowcount` / `aria-colcount` (all rows, not just the rendered ones), `aria-multiselectable`,
|
|
251
|
+
`aria-readonly`; header `role="columnheader"` with `aria-sort`; rows `role="row"` with `aria-rowindex` and
|
|
252
|
+
`aria-selected` (row mode); cells `role="gridcell"` with `aria-colindex`, `aria-selected` (cell mode) and
|
|
253
|
+
`aria-readonly` (editable grids). The grid keeps the focus and points at the current cell with
|
|
254
|
+
`aria-activedescendant`, so screen readers follow it through virtualization.
|
|
255
|
+
|
|
256
|
+
## Development
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
npm install
|
|
260
|
+
npm test # vitest + Testing Library (jsdom)
|
|
261
|
+
npm run typecheck
|
|
262
|
+
npm run build # dist/: ES modules, .d.ts, styles.css
|
|
263
|
+
npm run format:check
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## License
|
|
267
|
+
|
|
268
|
+
MIT
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { type ReactElement, type Ref } from 'react';
|
|
2
|
+
import type { DataGridHandle, DataGridProps } from './types';
|
|
3
|
+
export declare const defaultCompare: (a: unknown, b: unknown) => number;
|
|
4
|
+
/**
|
|
5
|
+
* Keyboard-first data grid: virtualized rows, row or cell selection with ranges, clipboard, in-place
|
|
6
|
+
* editing, sortable / resizable / reorderable / hideable / frozen columns. See README.
|
|
7
|
+
*/
|
|
8
|
+
export declare const DataGrid: <T>(props: DataGridProps<T> & {
|
|
9
|
+
ref?: Ref<DataGridHandle>;
|
|
10
|
+
}) => ReactElement;
|
|
11
|
+
//# sourceMappingURL=DataGrid.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"DataGrid.d.ts","sourceRoot":"","sources":["../src/DataGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,EAaL,KAAK,YAAY,EAGjB,KAAK,GAAG,EACT,MAAM,OAAO,CAAA;AA6Bd,OAAO,KAAK,EAMV,cAAc,EACd,aAAa,EAGd,MAAM,SAAS,CAAA;AAkChB,eAAO,MAAM,cAAc,MAAO,OAAO,KAAK,OAAO,KAAG,MAMvD,CAAA;AAs7BD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAgC,CAAC,CAAC,EACrD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAA;CAAE,KACpD,YAAY,CAAA"}
|